コンテンツへスキップ

拡張機能

拡張機能を使うと、シンプルな.jsonベースのAPIを使って、WordPressインストール内の登録済みブロックを拡張できます。block.json設定と似た仕組みで、コア、サードパーティ製、Blockstudioで作成したブロックが対象です。

すべてのフィールド型を任意のブロックに追加でき、データはブロックの属性に保存されます。フィルタリング、無効化、条件付きロジック、選択肢の設定など、属性の全機能を拡張機能でも利用できます。

拡張機能の種類

拡張した値は、さまざまな方法で利用できます。

  • class: 属性値を使ってブロックにクラスを追加
  • style: 属性値を使ってブロックにインラインスタイルを追加
  • attributes: ブロックに任意の属性値を直接設定
  • data属性: 拡張値を使って特定のdata属性を設定

セットアップ

次の例を考えてみましょう。すべてのコアブロックにカスタムクラスselectフィールドを追加したいとします。ブロックフォルダー内の任意の場所にこの.jsonファイルを置くだけで、拡張機能として自動登録されます。

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 で作成したブロックも含まれます:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

ブロックの除外

トップレベルの exclude 配列を使うと、本来なら name に一致するブロックをスキップできます:

JSON
{
  "$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: 高度な設定タブ
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

優先度

priorityプロパティで、拡張機能を表示する順序を指定できます。優先度が高い拡張機能ほど後に表示されます。セットアップ例のようにファイルのトップレベルに設定するか、extend内に設定してください。

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

両方に設定されている場合は、blockstudio.extend.priorityが優先されます。

属性

属性の仕組みについて詳しくは、属性のセクションを参照してください。

拡張機能で使う属性について覚えておく必要があるのは、setプロパティだけです。このプロパティは、属性の値を拡張機能の種類のいずれかに適用するために使います。

JSON
{
  "$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に設定した場合など、属性が単一の値を返さないときは、ネストされた値も取得できます。

JSON
{
  "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、または単一の値を返すフィールドには影響しません。

JSON
{
  "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() との関係については、ブロックの確認 を参照してください。