コンテンツへスキップ

カスタムフィールドタイプ

カスタムフィールドタイプを使うと、テーマやプラグインで新しいBlockstudioフィールドコントロールを追加できます。 カスタムフィールドとは異なります:

  • custom/{name}は、既存フィールドの再利用可能なグループを参照します。
  • namespace/type-nameは、独自のエディターコントロールと値の形式を持つ登録済みフィールドタイプを使用します。

Blockstudioは登録システムを提供します。コントロールはテーマまたはプラグインが提供します。

使用する場面

プロジェクトで、あらゆる場所でネイティブのBlockstudioフィールドのように動作する、単一用途の編集コントロールが必要な場合にカスタムフィールドタイプを使います:

  • ブロック属性
  • 再利用可能なcustom/{name}フィールドグループ
  • グループ、タブ、リピーター
  • PHP、Twig、Bladeテンプレート
  • 投稿メタデータとオプションの保存
  • {attributes.margin.top}などの拡張テンプレート

たとえば、間隔コントロールでは、4つの個別のテキストフィールドの代わりに1つのオブジェクトを保存できます:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

命名

カスタムフィールドタイプ名は小文字で、名前空間を持ち、ダッシュ区切りにする必要があります:

Text
namespace/type-name

有効な例:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

予約済みの名前空間:

  • custom/は再利用可能なカスタムフィールドグループ用に予約されています。
  • blockstudio/はBlockstudioコア用に予約されています。

無効な名前はフィルターAPIでは無視され、ヘルパーAPIでは拒否されます。

PHPの登録

フィールドタイプのメタデータをPHPに登録します:

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});

bs_register_field_type()は登録に成功するとtrueを返し、名前または定義が無効な場合はfalseを返します。手動で登録した項目はbs_unregister_field_type()で登録解除できます。

フィルターAPIも使用できます:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

定義キー

キー 型 説明
attribute string, array, null WordPress属性の型です。string、number、boolean、object、array、またはそれらの型の配列を使用します。
default mixed フィールドに独自のデフォルト値が定義されていない場合の、レジストリーレベルのデフォルト値です。
source string カスタムシリアライズの場合に使用するWordPress属性のソースです。
produces_attribute boolean 表示専用のコントロールではfalseに設定します。デフォルトはtrueです。
editor_script string or array この型を使用する際にブロックエディターで読み込む、登録済みスクリプトのハンドルです(複数可)。
editor_style string or array この型を使用する際にブロックエディターで読み込む、登録済みスタイルのハンドルです(複数可)。
storage array 投稿メタデータとオプションのストレージ値の型およびRESTスキーマのヒントです。
supports array 独自のコントロールに設定できる任意の機能フラグです。
translate boolean 値がWPMLで翻訳するテキストの場合はtrueに設定します。attribute stringが必要です。

translateの値がブール値でない定義、またはtranslateがtrueに設定され、attributeがstring以外の定義は無効です。 bs_register_field_type()はfalseを返し、APIフィルターはその定義を無視します。

WPML

wp bs wpml configは登録情報だけではカスタムフィールド型の値がテキストかどうか判断できないため、そのようなフィールドを除外し、それぞれに警告を表示します。プレーンテキスト文字列を保存するフィールド型の登録でtranslateをtrueに設定すると、このコマンドはそのフィールドをtextフィールドとして宣言します。フィールドでは"translate": falseを指定して対象外にすることもできます。詳しくはWPMLをご覧ください。

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

JavaScriptの登録

エディタースクリプトで、対応するReactコントロールを登録します:

JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

registerFieldType()は登録が受け入れられるとtrueを返します。クライアント側の登録は次のように削除できます:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

コンポーネントには、フィールド定義のプロパティに加えて、次の固定プロパティが渡されます:

プロパティ 説明
type フィールドタイプ名。
id フィールドID。
field block.jsonの完全なフィールド定義。
value 現在保存されている値。
defaultValue フィールドのデフォルト値。
onChange 新しい値を直接保存します。
attributes 現在のブロック属性。
block 現在のブロックタイプ定義。
clientId 現在のエディターブロックのクライアントID。
inRepeater フィールドがリピーターの行内にあるかどうか。
repeaterId 現在のリピーターパス(ある場合)。
disabled エディターでフィールドが無効になっているかどうか。

カスタムフィールドタイプの値は直接保存されます。標準のselect、radio、color、gradientのオプション正規化処理は適用されません。

値のレンダリング

オブジェクト値は、他のBlockstudio属性と同様に利用できます。

PHP

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

入れ子になったオブジェクトパスは拡張テンプレートでも機能します:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

保存

カスタムフィールドタイプをpostMetaまたはoptionストレージで使用すると、Blockstudioは登録された保存値の型とRESTスキーマを使用します。

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

arrayとobjectの値には、フィールドタイプの登録時にstorage.rest_schemaを定義します。リピーターは行を保存するため、その子孫は引き続き配列ベースのストレージを使用します。

フォールバック動作

PHPがフィールドタイプを認識していても、エディタースクリプトで対応するコントロールが登録されていない場合、Blockstudioは保存済みの値を保持し、エディターに編集不可の通知を表示します。フロントエンドのレンダリングでは、引き続き保存済みの値を受け取ります。

PHPにフィールドタイプが登録されていない場合、Blockstudioは生成されるWordPress属性からそのフィールドを除外します。ブロックの検出が実行される前にPHP定義を登録してください。通常は、Blockstudioがブロックを構築する前のinitで登録します。