コンテンツへスキップ

カスタムフィールド

カスタムフィールドを使うと、複数のブロックから参照できる再利用可能なフィールドグループを定義できます。フィールドテンプレートのように、一度定義すればどこでも使えます。

カスタムフィールドはカスタムフィールドタイプと同じではありません。既存フィールドの再利用可能なグループにはcustom/{name}を使います。テーマまたはプラグインで新しいエディターコントロールと値の形式を登録する場合は、acme/dimensionsのような名前空間付きのカスタムフィールドタイプを使います。

ファイルシステムでの登録

blockstudioディレクトリ内のfields/ディレクトリにfield.jsonファイルを作成します:

コード
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

PHPフィルターでの登録

blockstudio/fieldsフィルターを使って、プログラムからカスタムフィールドを登録します:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

block.jsonでの使用

custom/{name}タイプを使ってカスタムフィールドを参照します:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

これをインラインで展開すると、カスタムフィールド定義で定義されたフィールドになります。展開されたフィールドは元のID(heading、description、enabled)を使用します。

カスタムフィールドでは、グループ定義全体を再利用することもできます:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

グループの子要素はsection-header_kicker、section-header_titleなどとして保存されます。テンプレートではbs_get_group()を使って、子要素を整理されたグループオブジェクトに取り出します。

IDの構造

idStructureを使ってフィールドIDに接頭辞を付けたり、変換したりできます。{id}プレースホルダーは元のフィールドIDに置き換えられます:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

これにより、IDがhero_heading、hero_description、hero_enabledのフィールドが生成されます。

オーバーライド

overridesを使って、フィールドごとにインスタンス単位でカスタマイズできます。キーには定義内の元のフィールドIDを指定します:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

上書きプロパティは元のフィールド定義に追加でマージされます。idによる上書きではidStructureパターンが適用されません。上記の例では、enabledはhero_enabledではなくactiveになります。

マージは1階層のみです。上書きしたプロパティは、元のプロパティ全体を置き換えます。optionsの上書きではオプション一覧全体が置き換わり、追加されるわけではありません。conditionsとグループのattributesも同様です。参照先の条件はその後も追加されます。

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

このブロックで選べるのは White と Grey のみです。定義にいくつ選択肢が記載されていても変わりません。

条件

カスタムフィールド定義内の条件は、idStructureが適用されると自動的に書き換えられます。兄弟フィールドに条件付きで依存するフィールドも、展開後に引き続き機能します。

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudioはこれをtitle_font_enable、title_font_min、title_font_maxに展開し、条件を書き換えて、enableではなくtitle_font_enableを参照します。トグルコントロールは、フィールドをインラインで定義した場合とまったく同じように動作します。

参照レベルの条件

参照にconditionsを追加すると、展開されるすべてのフィールドに条件を適用できます。外部トグルを使ってグループ全体を非表示にする場合に便利です:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

これらの条件は、フィールド定義内ですでに定義されている条件とマージされます。条件IDもidStructureによって書き換えられます。

複数のカスタムフィールド

1つのブロック内で、通常のフィールドと並べて複数のカスタムフィールドを使用できます:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

入れ子構造

カスタムフィールドはグループ、タブ、リピーターの内部でも使用できます:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

追加の検出パス

blockstudio/fields/pathsフィルターを使って、フィールド検出の対象ディレクトリを追加します:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

静的解析

blockstudio/phpstanパッケージは、ファイルベースのcustom/*参照を展開し、PHP、Twig、Blade、ブロックタグ、および推定される属性の形式を検証します。展開の際には、上記で説明したものと同じ入れ子構造、idStructure、overridesのルールに従います。

解析対象のプロジェクト外にある定義については、ライブラリディレクトリをphpstan.neon内のblockstudioScanRootsに追加します。blockstudio/fieldsPHPフィルターのみで登録されたフィールドは実行時に存在するため、静的には推論できません。