サポート

ブロックは「ブロックサポート」API を使用して、特定の機能のサポートを宣言できます。

機能にオプトインすると、ブロックに追加の属性が登録され、属性を操作するUIが提供されます。

ブロックに属性を適用するために、生成されたプロパティがブロックのラッパー要素に追加されます。これらのプロパティは useBlockProps フックから返されるオブジェクトに追加されます。

BlockEdit 関数:

functionBlockEdit() {
	const blockProps = useBlockProps();

	return (
		<div {...blockProps}>Hello World!</div>
	);
}

save 関数:

functionBlockEdit() {
	const blockProps = useBlockProps.save();

	return (
		<div {...blockProps}>Hello World!</div>
	);
}

PHP の render_callback でレンダーされるダイナミックブロックでは、get_block_wrapper_attributes() 関数を使用できます。生成されたすべてのプロパティを含む文字列が返されます。これをラップするブロック要素の開始タグに出力する必要があります。

render_callback 関数:

function render_block() {
	$wrapper_attributes = get_block_wrapper_attributes();

	returnsprintf(
		'<div %1$s>%2$s</div>',
		$wrapper_attributes,
		'Hello World!'
	);
}

• タイプ: boolean
• デフォルト値: false

アンカーを使用するとページ上の特定のブロックに直接リンクできます。このプロパティはブロックの ID を定義するフィールドと、ダイレクトリンクをコピーするボタンをを追加します。重要: ダイナミックブロックでは、まだ、動作しません。

// アンカーリンクのサポートを宣言supports: {
    anchor: true
}

• タイプ: boolean または array
• デフォルト値: false

このプロパティはブロックの配置を変更するブロックコントロールを追加します。

supports: {
    // ブロックの配置のサポートを宣言// すべてのオプションのサポートを追加// left (左寄せ), center (中央寄せ), right (右寄せ), wide (幅広), full (全幅)align: true
}

supports: {
    // 特定の配置のオプションのサポートを宣言align: [ 'left', 'right', 'full' ]
}

ブロックが align サポートを宣言するとブロック属性定義が拡張され、string タイプの align 属性が含まれます。デフォルトでは配置は割り当てられません。ブロックにデフォルトの配置を適用するには、デフォルト値と共に align 属性を指定します。たとえば

attributes: {
    align: {
        type: 'string',
        default: 'right'
    }
}

• タイプ: boolean
• デフォルト値: true

このプロパティを使用するとテーマの 幅広揃え を有効化できます。単一ブロックに対してこの機能を無効化するにはこのフラグに false を設定してください。

supports: {
    // 幅広揃えサポートを除去alignWide: false
}

• タイプ: boolean
• デフォルト値: true

デフォルトでは保存したマークアップの root 要素にクラス .wp-block-your-block-name が追加されます。この結果、テーマやプラグインがブロックをスタイリングする際に利用可能な一貫した機構が実現します。何らかの理由によりこのクラスをマークアップに付加したくない場合、この機能を無効化できます。

supports: {
    // className 生成サポートを除去className: false
}

• タイプ: Object
• デフォルト値: null
• サブプロパティ:
  • background: タイプ boolean, デフォルト値 true
  • __experimentalDuotone: タイプ string, デフォルト値なし
  • gradients: タイプ boolean, デフォルト値 false
  • link: タイプ boolean, デフォルト値 false
  • text: タイプ boolean, デフォルト値 true

この値はブロックが色に関連するプロパティをサポートすることを通知します。サポートする場合、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

注意: background キーとtext キーのデフォルト値は true です。color プロパティを宣言するとこれらも有効化されます。

supports: {
    color: { // 同時にテキスト UI コントロールと背景 UI コントロールも有効化gradients: true// グラデーション UI コントロールを有効化
    }
}

これらは個別に無効化できます。

supports: {
    color: { // テキスト UI コントロールは有効background: false, // 背景 UI コントロールを無効化gradients: true// グラデーション UI コントロールを有効化
    }
}

このプロパティは UI コントロールを追加します。ユーザーは UI コントロールを使用してブロックに背景色を適用できます。

color サポートを宣言すると、background プロパティは text プロパティと共に自動で有効化されます。このため単に color を設定すれば、背景色は有効化されます。

supports: {
    color: true// background と text の両方を有効化
}

他の color サポートは有効化しながら background サポートを無効化するには、false を設定します。

supports: {
    color: {
        // background サポートを無効化。テキスト色のサポートは引き続き有効background: false
    }
}

ブロックが color.background のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 backgroundColor と style が含まれます。

• backgroundColor: タイプ string の属性。デフォルト値なし。

プリセットのリストからユーザーが背景色を選択すると、プリセットのスラッグが backgroundColor 属性に保存されます。

背景色プリセットは editor-color-palette テーマサポート がソースです。

ブロックはデフォルトのプリセット背景色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    backgroundColor: {
        type: 'string',
        default: 'some-preset-background-slug',
    }
}

• style: タイプ object の属性。デフォルト値なし。

カスタムカラーピッカーを使用するなどして、カスタム背景色を選択すると、カスタムカラー値が style.color.background 属性に保存されます。

ブロックはデフォルトのカスタム背景色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                background: '#aabbcc',
            }
        }
    }
}

このプロパティは UI コントロールを追加します。ブロック、またはブロックの一部にデュオトーンフィルターを適用できます。

親のセレクタが、Sass/SCSS でのネストのように自動で追加されます (しかし、& セレクタはサポートされません)。

supports: {
    color: {
        // edit と save 両方の同じセレクタにフィルターを適用する。__experimentalDuotone: '> .duotone-img, > .duotone-video',

        // デュオトーンと一緒にデフォルト値を使いたくない場合は、無効化する必要があるbackground: false,
        text: false
    }
}

デュオトーンプリセットは、theme.json の color.duotone がソースです。

ブロックが color.__experimentalDuotone のサポートを宣言すると、属性定義が拡張され、属性 style が含まれます。

• style: タイプ object の属性。デフォルト値なし。

ブロックはデフォルトのデュオトーンカラーを適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                duotone: [
                    '#FFF',
                    '#000'
                ]
            }
        }
    }
}

このプロパティは UI コントロールを追加します。ユーザーは UI コントロールを使用して、ブロックにグラデーション背景を適用できます。

supports: {
    color: {
        gradients: true,

        // グラデーションと一緒にデフォルト値を使いたくない場合は、無効化する必要があるbackground: false,
        text: false
    }
}

グラデーションプリセットは editor-gradient-presets テーマサポート がソースです。

ブロックが color.gradient のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 gradient と style が含まれます。

• gradient: タイプ string の属性。デフォルト値なし。

プリセットのリストからユーザーがグラデーションを選択すると、プリセットのスラッグが gradient 属性に保存されます。

ブロックはデフォルトのグラデーションプリセットを適用できます。これには 自身の属性に default で指定します。

attributes: {
    gradient: {
        type: 'string',
        default: 'some-preset-gradient-slug',
    }
}

• style: タイプ object の属性。デフォルト値なし。

カスタムグラデーションピッカーを使用するなどして、カスタムグラデーションを選択すると、カスタムグラデーション値が style.color.gradient 属性に保存されます。

ブロックはデフォルトのカスタムグラデーションを適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                gradient: 'linear-gradient(135deg,rgb(170,187,204) 0%,rgb(17,34,51) 100%)',
            }
        }
    }
}

このプロパティは、ユーザーがブロック内のリンクの色を設定できるブロックコントロールを追加します。デフォルトではリンクの色は無効です。

supports: {
    color: true// Enables only background and text
}

リンクの色のサポートを有効にするには、true に設定します。

supports: {
    color: {
        link: true
    }
}

リンクの色のプリセットは、editor-color-palette テーマサポートをソースとしています。

ブロックが color.link のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 linkColor と style が追加されます。

• linkColor: string 型の属性で、デフォルトは割り当てられていません。

ユーザーがプリセットのリンクの色のリストから選択すると、プリセットのスラッグが linkColor 属性に格納されます。

ブロックにデフォルトのプリセットのテキスト色を適用するには、自身の属性にデフォルトを指定します。例:

attributes: {
    linkColor: {
        type: 'string',
        default: 'some-preset-link-color-slug',
    }
}

• style: object 型の属性で、デフォルトは割り当てられていません。

カスタム色ピッカーを使用するなどして、カスタムリンクの色が選択されると、カスタム色の値が style.color.link 属性に格納されます。

ブロックにデフォルトのカスタムリンクの色を適用するには、自身の属性をデフォルトで指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                link: '#ff0000',
            }
        }
    }
}

このプロパティはブロックコントロールを追加します。ユーザーはブロックコントロールを使用してブロックのテキスト色を設定できます。

color サポートを宣言すると、text プロパティは background プロパティと共に自動で有効化されます。このため単に color を設定すれば、テキスト色は有効化されます。

supports: {
    color: true// background と text を有効化。link は有効化しない。
}

他の color サポートは有効化しながら text サポートを無効化するには、false を設定します。

supports: {
    color: {
        // text サポートを無効化。text: false
    }
}

テキスト色プリセットは editor-color-palette テーマサポート がソースです。

ブロックが color.text のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 textColor と style が含まれます。

• textColor: タイプ string の属性。デフォルト値なし。

プリセットのリストからユーザーがテキスト色を選択すると、プリセットのスラッグが textColor 属性に保存されます。

ブロックはデフォルトのプリセットテキスト色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    textColor: {
        type: 'string',
        default: 'some-preset-text-color-slug',
    }
}

• style: タイプ object の属性。デフォルト値なし。

カスタムカラーピッカーを使用するなどして、カスタムテキスト色を選択すると、カスタムカラー値が style.color.gradient 属性に保存されます。

ブロックはデフォルトのカスタムテキスト色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                text: '#aabbcc',
            }
        }
    }
}

• タイプ: boolean
• デフォルト値: true

このプロパティはブロックのラッパーのカスタム classsName を定義するフィールドを追加します。

supports: {
    // カスタム className サポートを除去customClassName: false
}

• タイプ: boolean
• デフォルト値: true

スタイルピッカーの表示の際、ブロックの現在のアクティブなスタイルに基づいてブロックタイプのデフォルトのスタイルを設定できます。このオプションを有効にしたくない場合は、false に設定してください。

supports: {
    // デフォルトのスタイルピッカーを除去defaultStylePicker: false
}

• タイプ: boolean
• デフォルト値: false

この値はブロックが font-size CSS スタイルプロパティをサポートすることを通知します。サポートする場合、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

このコントロール内に表示される値は editor-font-sizes テーマサポート でテーマが宣言したもの、または指定がなければデフォルトのものになります。

supports: {
    // font-size UI コントールの有効化fontSize: true,
}

ブロックが fontSize サポートを宣言すると、attributes の定義も新しい属性 fontSize と style を含むよう拡張されます。

• fontSize: string タイプの属性で、デフォルトの割り当てはありません。ユーザーによるプリセットした値のセットを保存します。ブロックは自身の fontSize 属性とデフォルトを指定することで、デフォルトの fontSize を適用できます。

attributes: {
    fontSize: {
        type: 'string',
        default: 'some-value',
    }
}

• style: object タイプの属性で、デフォルトの割り当てはありません。ユーザーによるプリセットした値のセットを保存します。ブロックは自身の style 属性とデフォルトを指定することで、デフォルトのスタイルを適用できます。

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                fontSize: 'value'
            }
        }
    }
	defaultStylePicker: false
}

• タイプ: boolean
• デフォルト値: true

デフォルトではブロックのマークアップは個別に編集できます。この動きを止めるには html に false を設定してください。

supports: {
    // HTML モードサポートを除去html: false
}

• タイプ: boolean
• デフォルト値: true

デフォルトではすべてのブロックはインサーターに表示されます。ブロックをインサーターには表示せず、プログラム的にのみ挿入可能にするには inserter に false を設定してください。

supports: {
    // このブロックをインサーターに表示しないinserter: false
}

• タイプ: boolean
• デフォルト値: true

非 multiple ブロックは各投稿に1回だけ挿入できます。たとえば組み込みの「続きを読む」ブロックは、編集中の投稿にすでに存在する場合は挿入できません。非 multiple ブロックのアイコンはクリックできないよう自動的にグレイアウトされ、複数インスタンスの作成を回避します。

supports: {
    // ブロックは投稿ごとに1度だけ使用できるmultiple: false
}

• タイプ: boolean
• デフォルト値: true

ブロックを再利用可能なブロックに変換する機能を無効化したい場合があります。デフォルトではすべてのブロックは再利用可能ブロックに変換できます。reusable サポートを false に設定すると、再利用可能ブロックするに変換するオプションが表示されません。

supports: {
    // 再利用可能ブロックへの変換を許可しないreusable: false,
}

• タイプ: boolean
• デフォルト値: true

ブロックは、ロック状態を切り替える機能を無効化したい場合があります。デフォルトでは、ブロックの「オプション」ドロップダウンから、ユーザーによるロック、ロック解除が可能です。この動作を無効にするには、lock を false に設定します。

supports: {
	// ロック UI のサポートを削除。lock: false
}

• タイプ: Object
• デフォルト値: null
• サブプロパティ:
  • margin: タイプ boolean または array, デフォルト値 false
  • padding: タイプ boolean または array, デフォルト値 false
  • blockGap: タイプ boolean または array, デフォルト値 false

この値はブロックがスペースに関連する CSS スタイルプロパティをサポートすることを通知します。テーマがサポートを宣言するなら、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

supports: {
    spacing: {
        margin: true,  // margin UI コントロールを有効化padding: true, // padding UI コントロールを有効化blockGap: true,  // block spacing UI コントロールを有効化
}

ブロックが spacing プロパティのサポートを宣言すると、attributes の定義も style 属性を含むよう拡張されます。

• style: デフォルトの割り当てのない object タイプの属性。margin または padding サポートを宣言すると追加されます。ユーザーによるカスタム値のセットを保存します。例:

attributes: {
    style: {
        margin: 'value',
        padding: {
            top: 'value',
        }
    }
}

spacing プロパティは構成可能なサイド、’top’、’right’、’bottom’、’left’ の配列を定義することもできます。任意のサイドが UI コントロールに定義されると、そのサイドが表示されます。

軸方向のサイドは vertical と horizontal で定義され、軸方向のペアごとに1つの UI コントロールが表示されます (例えば、vertical は上辺と下辺の両方を制御します)。spacing プロパティは、任意の個別のサイド、または、軸方向のサイドをサポートできますが、両方を混ぜることはできません。

注意: blockGap は軸方向のサイド vertical と horizontal を取り、列値と行値のスペースを調整します。blockGap は任意方向のサイドをサポートしまsん。

supports: {
    spacing: {
        margin: [ 'top', 'bottom' ],             // 任意のサイドのマージンを有効化する。padding: true,                           // すべてのサイドのパディングを有効化する。blockGap: [ 'horizontal', 'vertical' ],  // 軸方向 (列/行) のブロックのスペース制御を有効化する。
    }
}

• タイプ: Object
• デフォルト値: null
• サブプロパティ:
  • fontSize: タイプ boolean、デフォルト値 false
  • lineHeight: タイプ boolean、デフォルト値 false

このオブジェクトが存在すると、ブロックがいくつかのタイポグラフィ関連のプロパティをサポートすることを通知します。サポートする場合、ブロックエディタにはタイポグラフィのUIが表示され、ユーザーは値を制御できます。

supports: {
    typography: {
        // font-size のサポートと UI コントロールを有効化fontSize: true,
        // line-height のサポートと UI コントロールを有効化lineHeight: true,
    },
}

• タイプ: boolean
• デフォルト値: false

この値はブロックが font-size CSS スタイルプロパティをサポートすることを通知します。サポートする場合、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

このコントロール内に表示される値は editor-font-sizes テーマサポート でテーマが宣言したもの、または指定がなければデフォルトのものになります。

supports: {
    typography: {
        // font-size のサポートと UI コントールの有効化fontSize: true,
    },
}

ブロックが fontSize サポートを宣言すると、attributes の定義も新しい属性 fontSize と style を含むよう拡張されます。

• fontSize: string タイプの属性で、デフォルトの割り当てはありません。ユーザーが選択したプリセット値のセットを保存します。ブロックは自身の fontSize 属性とデフォルトを指定することで、デフォルトの fontSize を適用できます。

attributes: {
    fontSize: {
        type: 'string',
        default: 'some-value',
    }
}

• style: object タイプの属性で、デフォルトの割り当てはありません。ユーザーによるカスタム値のセットを保存し、色などの他のブロックサポートと共有されます。ブロックは自身の style 属性とデフォルトを指定することで、デフォルトのスタイルを適用できます。

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                fontSize: 'value'
            }
        }
    }
}

• タイプ: boolean
• デフォルト値: false

この値はブロックが line-height CSS スタイルプロパティをサポートすることを通知します。サポートする場合、テーマがサポートを宣言するなら、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

supports: {
    typography: {
        // line-height のサポートと UI コントロールを有効化lineHeight: true,
    },
}

ブロックが lineHeight プロパティのサポートを宣言すると、attributes の定義も新しい属性 style を含むよう拡張されます。style は obuject タイプの属性で、デフォルトの割り当てはありません。ユーザーによるプリセットした値のセットを保存します。ブロックは自身の style 属性とデフォルトを指定することで、デフォルトの style を適用できます。

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                lineHeight: 'value'
            }
        }
    }
}

原文

最終更新日: 2022年7月17日