拡張機能
拡張機能を使うと、シンプルな.jsonベースのAPIを使って、WordPressインストール内の登録済みブロックを拡張できます。block.json設定と似た仕組みで、コア、サードパーティ製、Blockstudioで作成したブロックが対象です。
すべてのフィールド型を任意のブロックに追加でき、データはブロックの属性に保存されます。フィルタリング、無効化、条件付きロジック、選択肢の設定など、属性の全機能を拡張機能でも利用できます。
拡張機能の種類
拡張した値は、さまざまな方法で利用できます。
- class: 属性値を使ってブロックにクラスを追加
- style: 属性値を使ってブロックにインラインスタイルを追加
- attributes: ブロックに任意の属性値を直接設定
- data属性: 拡張値を使って特定のdata属性を設定
セットアップ
次の例を考えてみましょう。すべてのコアブロックにカスタムクラスselectフィールドを追加したいとします。ブロックフォルダー内の任意の場所にこの.jsonファイルを置くだけで、拡張機能として自動登録されます。
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
これにより、すべてのコアブロックにcustomColorフィールドが追加され、ブロック内のテキスト色を設定できるようになります。
ファイル名
レンダリングテンプレートがないため、拡張機能には対応するindexファイルが不要で、block.jsonという名前にする必要もありません。そのため、すべての拡張機能を1つのフォルダーにまとめて保存できます。複数のファイルで同じブロックを拡張することもできます。たとえば、"name": "core/*"を持つ2つのファイルがそれぞれ独自のフィールドを登録できます。
スキーマ
Blockstudioは拡張機能の設定用に独自のJSONスキーマを提供します。
名前
設定オブジェクトのnameプロパティで、拡張するブロックを指定します。用途に応じて、次の3つの方法を選べます。
- blockName: 単一のブロック名、e.g。
core/paragraph - [blockNameA, blockNameB]: ブロック名の配列、e.g。
["core/paragraph", "core/heading"] - core/*: 特定の種類のブロックをすべて拡張するワイルドカード
アスタリスクで終わる名前はすべて、core/* だけでなく、前方一致のワイルドカードです。次の拡張機能は、名前が my-plugin/ で始まるすべてのブロックに適用され、Blockstudio で作成したブロックも含まれます:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
ブロックの除外
トップレベルの exclude 配列を使うと、本来なら name に一致するブロックをスキップできます:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
除外では、name と同じ完全一致名および末尾の * による前方一致が使われます。除外は単一名、名前リスト、ワイルドカードより優先されます。除外されたブロックには、拡張機能のエディターフィールドも、フロントエンド属性やアセットも適用されません。他の一致する拡張機能には影響しません。既存の動作を維持するには、exclude を省略するか、空の配列を指定します。
Blockstudioキー
カスタムブロックでblock.jsonを使う場合と同様に、設定オブジェクトにはblockstudioプロパティが必要で、extendをtrueに設定します。
配置
デフォルトでは、拡張機能はブロックインスペクター内の独自のタブに表示されます。別の位置に移動するには、groupプロパティを使います。
- settings: デフォルトの位置
- styles: スタイルタブ
- advanced: 高度な設定タブ
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
優先度
priorityプロパティで、拡張機能を表示する順序を指定できます。優先度が高い拡張機能ほど後に表示されます。セットアップ例のようにファイルのトップレベルに設定するか、extend内に設定してください。
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
両方に設定されている場合は、blockstudio.extend.priorityが優先されます。
属性
属性の仕組みについて詳しくは、属性のセクションを参照してください。
拡張機能で使う属性について覚えておく必要があるのは、setプロパティだけです。このプロパティは、属性の値を拡張機能の種類のいずれかに適用するために使います。
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
値の取得
属性の値を取得するには、中かっこ内でドット記法を使います。
フィールド型の戻り値形式をbothに設定した場合など、属性が単一の値を返さないときは、ネストされた値も取得できます。
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
上の例では、値に応じてstyle属性をcolor: #f00またはcolor: #00fに、data-color属性をRedまたはBlueに設定します。
現時点では、set定義内で使えるのは現在の属性の値だけです。将来的には、他の属性の値も使えるようになる可能性があります。
配列
配列を使う場合、setプロパティは配列内の各項目に適用されます。
各項目は、それぞれ独自のクラスまたはスタイル宣言を追加します。それ以外の属性には単一の値が格納されるため、項目ごとに上書きされ、最後の項目が有効になります。join を true に設定すると、すべての項目の結果が空値や重複値を除いてスペース区切りで出力されるため、[data-langs~="en"] のようなセレクターが選択したすべての項目に一致します。join は class と style、または単一の値を返すフィールドには影響しません。
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
両方のオプションを選ぶと、data-langs="en de" が出力されます。join がない場合は、data-langs="de" が出力されます。
Attributesフィールド
attributesフィールドを使う場合、値が属性名と属性値に自動的に対応付けられるため、setプロパティは不要です。
拡張フィールドの確認
bs_block_extension_fields('core/paragraph') は、ブロックに一致するすべての拡張機能のフィールド定義を返します。戻り値と bs_block_fields() との関係については、ブロックの確認 を参照してください。