カスタムフィールドタイプ
カスタムフィールドタイプを使うと、テーマやプラグインで新しいBlockstudioフィールドコントロールを追加できます。 カスタムフィールドとは異なります:
custom/{name}は、既存フィールドの再利用可能なグループを参照します。namespace/type-nameは、独自のエディターコントロールと値の形式を持つ登録済みフィールドタイプを使用します。
Blockstudioは登録システムを提供します。コントロールはテーマまたはプラグインが提供します。
使用する場面
プロジェクトで、あらゆる場所でネイティブのBlockstudioフィールドのように動作する、単一用途の編集コントロールが必要な場合にカスタムフィールドタイプを使います:
- ブロック属性
- 再利用可能な
custom/{name}フィールドグループ - グループ、タブ、リピーター
- PHP、Twig、Bladeテンプレート
- 投稿メタデータとオプションの保存
{attributes.margin.top}などの拡張テンプレート
たとえば、間隔コントロールでは、4つの個別のテキストフィールドの代わりに1つのオブジェクトを保存できます:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
命名
カスタムフィールドタイプ名は小文字で、名前空間を持ち、ダッシュ区切りにする必要があります:
namespace/type-name
有効な例:
acme/dimensionsacme/text-optionstheme/spacing-token
予約済みの名前空間:
custom/は再利用可能なカスタムフィールドグループ用に予約されています。blockstudio/はBlockstudioコア用に予約されています。
無効な名前はフィルターAPIでは無視され、ヘルパーAPIでは拒否されます。
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も使用できます:
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をご覧ください。
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScriptの登録
エディタースクリプトで、対応するReactコントロールを登録します:
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を返します。クライアント側の登録は次のように削除できます:
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
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
入れ子になったオブジェクトパスは拡張テンプレートでも機能します:
{
"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スキーマを使用します。
{
"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で登録します。