自作のカスタムブロックに「幅を全幅にする」「文字色を変える」「余白を調整する」といった設定を付けたいとき、コントロールを自分で並べて属性を保存する必要はありません。block.json の supports に1行書き足すだけで、コアブロックと同じ設定 UI と保存処理がそのまま使えます。この記事では align / color / typography / spacing といった主な項目の書き方と、useBlockProps 側で必要になる受け取り方、そして「書いたのに設定が出てこない」ときの原因を解説します。WordPress 6 系のブロックエディターを前提としています。
目次
supports はエディターの標準機能を借りる設定
supports は、ブロックがエディターのどの機能に対応するかを宣言する項目です。ここで true にした機能について、ブロックエディターは設定 UI の表示・属性の追加・クラス名や style 属性の生成までを自動でやってくれます。たとえば "align": true と書けば、ツールバーに配置のメニューが現れ、選んだ値が align 属性に保存され、出力される HTML に alignwide のようなクラスが付きます。attributes に align を書く必要はありません。
自分で SelectControl を置いて属性を定義するのとの違いは、テーマの設定（theme.json）やコアブロックと足並みが揃うことです。テーマが用意したカラーパレットや余白のスケールがそのまま選択肢として出てくるので、サイト全体で統一感のある見た目になります。逆に言えば、テーマ側が対応していない機能はコントロールが出てきません。この点はあとの「設定が出てこないとき」で詳しく説明します。
よく使う supports の項目
項目は数が多いので、まずは使用頻度の高いものを押さえておくとよいでしょう。「既定値」は、何も書かなかったときにどう扱われるかを示しています。
| 項目 | できること | 既定値 |
|---|---|---|
align | 左寄せ・中央・右寄せ・幅広・全幅の配置を選べるようにする | false |
color | 文字色・背景色・グラデーション・リンク色の設定を追加する | false |
typography | 文字サイズ・行の高さなど文字まわりの設定を追加する | false |
spacing | 余白（margin・padding）や子要素の間隔の設定を追加する | false |
anchor | 「HTML アンカー」欄を出し、id 属性を出力する | false |
className | wp-block-<名前> クラスを自動で付ける | true |
customClassName | 「追加 CSS クラス」欄を出す | true |
html | 「HTML として編集」を許可する | true |
multiple | 同じ投稿内に複数個入れられるようにする | true |
inserter | ブロック挿入ツールの一覧に表示する | true |
前半の align から anchor までは「書くと機能が増える」もの、後半の className 以降は「既定で有効なので、切りたいときに false と書く」ものです。この違いを意識しておくと、書き忘れなのか意図的な無効化なのかで迷わなくなります。
align で配置を選べるようにする
いちばん手軽に効果が分かるのが align です。true にするとすべての配置が選べるようになりますが、実際には配列で絞り込むことが多いでしょう。
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "webool/notice",
"title": "お知らせボックス",
"category": "design",
"attributes": {
"content": {
"type": "string",
"source": "html",
"selector": "p"
}
},
"supports": {
"align": [ "wide", "full" ]
},
"editorScript": "file:./index.js",
"style": "file:./style-index.css"
}この状態でブロックを選ぶと、ツールバーに「幅広」「全幅」だけが並んだ配置メニューが出ます。選んだ値は align 属性に入り、たとえば全幅なら alignfull というクラスが出力されます。[ "left", "center", "right" ] のように書けば文字まわりの回り込み用の配置になります。
大事なのは、このクラスを HTML に付ける役目は useBlockProps が担っているという点です。edit.js と save.js の両方で useBlockProps をルート要素に展開しておく必要があります。
import { useBlockProps, RichText } from '@wordpress/block-editor';
export default function save( { attributes } ) {
// supports で有効にした機能のクラス・style はここで受け取る
const blockProps = useBlockProps.save();
return (
<div { ...blockProps }>
<RichText.Content tagName="p" value={ attributes.content } />
</div>
);
}useBlockProps.save() は className と style をまとめたオブジェクトを返します。これをルート要素に展開しないと、設定 UI では値が変わるのに HTML には何も反映されません。動的ブロックで render.php を使っている場合は、代わりに PHP 側で get_block_wrapper_attributes() を出力します。
<?php
/**
* 動的ブロックでは get_block_wrapper_attributes() が
* useBlockProps.save() と同じ役目を果たす
*/
?>
<div <?php echo get_block_wrapper_attributes(); ?>>
<?php echo wp_kses_post( $attributes['content'] ?? '' ); ?>
</div>color・typography で見た目の設定を追加する
color と typography は、真偽値ではなくオブジェクトで「どの項目を出すか」を細かく指定します。まとめて true にはできないので、必要なものを列挙します。
"supports": {
"align": [ "wide", "full" ],
"color": {
"text": true,
"background": true,
"gradients": true,
"link": false
},
"typography": {
"fontSize": true,
"lineHeight": true
},
"anchor": true
}color のうち text と background は、color を書いた時点で既定が有効です。gradients と link は既定が無効なので、使いたければ明示します。逆に「背景色は不要、文字色だけ」という場合は "background": false と書いて外します。
保存される HTML はどうなるか
ここで生成される値は、選び方によって保存先が変わります。テーマのパレットから選んだ色はクラス名として、カラーピッカーで自由に指定した色はinline style として保存されます。前者はテーマの CSS 変数を経由するため、あとからパレットの色を変えれば追従するという利点があります。
| 選び方 | 保存される属性 | 出力される HTML |
|---|---|---|
| パレットの色を選ぶ | textColor / backgroundColor | class="has-text-color has-primary-color" |
| カスタムの色を指定する | style（オブジェクト） | style="color:#1a73e8" |
| プリセットの文字サイズ | fontSize | class="has-large-font-size" |
| 行の高さを指定する | style（オブジェクト） | style="line-height:1.8" |
いずれも attributes に自分で書く必要はなく、useBlockProps がクラスと style に変換してくれます。ブロック側の CSS を書くときは、has-background が付いたときだけ padding を足す、といった作りにしておくと素直に馴染みます。
spacing で余白を調整できるようにする
余白は spacing で有効にします。padding と margin、それに子要素どうしの間隔である blockGap があります。
"supports": {
"spacing": {
"padding": true,
"margin": [ "top", "bottom" ],
"blockGap": true
}
}true にすると上下左右すべてが調整できますが、上の例の margin のように配列で辺を絞れます。横方向の margin まで自由に触られるとレイアウトが崩れやすいので、[ "top", "bottom" ] に限定するのは実用的な選択です。
ここには落とし穴がひとつあります。spacing はブロック側で有効にしただけでは UI が出ません。テーマの theme.json でも余白の設定が許可されている必要があります。ブロックテーマでない、あるいは theme.json を置いていないテーマでコントロールが出てこないときは、こちらを確認してください。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"spacing": {
"padding": true,
"margin": true,
"blockGap": true
}
}
}既定で有効な項目を切る使い方
supports は機能を足すだけでなく、余計なものを外すのにも使います。とくにブロックの構造が決まっていて崩されたくないときに効きます。
"supports": {
"html": false,
"customClassName": false,
"multiple": false
}"html": false は、ブロックメニューの「HTML として編集」を消します。マークアップを直接いじられるとブロック検証エラーの原因になるため、構造が固定のブロックでは切っておくのが無難です。"customClassName": false は「追加 CSS クラス」欄を隠し、"multiple": false は同じ投稿に2つ目を挿入できなくします（目次ブロックのような、1投稿に1つだけのブロックに向いています）。
もうひとつ知っておきたいのが className です。既定では wp-block-webool-notice のようなクラスが自動で付きますが、"className": false にするとこれが消えます。そのクラスを CSS のセレクターに使っているなら、外した瞬間にスタイルが当たらなくなるので注意してください。
supports を書いたのに設定が出てこないとき
ビルド後の block.json が更新されていない
@wordpress/scripts を使っている場合、WordPress が読むのは src/block.json ではなく build/block.json です。src を編集しただけでは反映されないので、npm start を動かしたまま作業するか、npm run build を実行し直します。そのうえでエディターの画面をスーパーリロード（ブラウザーのキャッシュを無視した再読み込み）してください。
useBlockProps を通していない
設定 UI は出るのに HTML が変わらない、というときはほぼこれです。edit.js と save.js のルート要素に { ...useBlockProps() } / { ...useBlockProps.save() } を展開しているか確認します。className を自分で書いて上書きしてしまっているケースもあるので、独自のクラスを足したいときは useBlockProps( { className: 'my-notice' } ) のように引数で渡します。あわせて block.json の apiVersion が 2 以上（現在は 3 が推奨）になっているかも見ておきましょう。useBlockProps は apiVersion 1 では機能しません。
テーマ側が対応していない
spacing のほか、align の「幅広」「全幅」もテーマの対応が前提です。クラシックテーマでは functions.php に add_theme_support( 'align-wide' ) が書かれていないと選択肢が出ません。ブロックテーマなら theme.json の settings.layout が働きます。色や文字サイズの選択肢が少ない場合も、テーマのパレット定義がそのまま反映されている結果です。
公開済みの投稿でブロック検証エラーが出た
supports を増やすとルート要素に付くクラスが変わるため、すでに保存済みの投稿を開いたときに「このブロックには想定されていないエラーが含まれています」と表示されることがあります。ほとんどの追加は既存の HTML と互換なので問題は起きませんが、className を false にしたときのようにクラスが消える変更では発生します。その場合は、以前の save の出力を deprecated として登録し、古い HTML も読めるようにするのが正しい対処です。
まとめ
supports は、自作ブロックにコアブロック相当の設定を持たせるためのいちばん短い道です。配置なら align、色と文字なら color と typography、余白なら spacing。どれも属性を自分で定義する必要はなく、値の保存とクラス・style への変換はエディターがやってくれます。
実装で気をつける点は2つに絞れます。ひとつは useBlockProps（動的ブロックなら get_block_wrapper_attributes()）をルート要素に必ず通すこと。もうひとつは、UI が出ないときにブロック側だけでなく theme.json やビルド結果まで疑うことです。まずは align だけを足して、クラスが出力されるところまで確認してから項目を増やしていくと、原因の切り分けが楽になります。