カスタムフィールドタイプの構築
値には単一のプリミティブでは表せないものがあります。価格は金額と通貨で構成されます。組み込みフィールドを使う場合、数値フィールドと選択フィールドを並べて表現します。価格を表示する各ブロックで、その組み合わせ、ラベル、そして両者を結び付けるロジックを繰り返すことになります。投稿メタでは2つのキーになり、リピーター内では並行する2つのリストになります。
カスタムフィールドタイプを使うと、この組み合わせを1つのフィールドにまとめられます。PHPとJavaScriptで、acme/priceのようなタイプを一度登録すれば、あとはネイティブフィールドと同じように、どのblock.jsonでも使えます。トップレベル、グループやリピーター内、投稿メタやオプションへの保存、さらにPHP、Twig、Bladeテンプレートでも利用できます。Blockstudioは登録内容からWordPress属性と保存用のRESTスキーマを導きます。
これはカスタムフィールドとは異なります。custom/{name}参照では、既存のフィールドグループを再利用します。カスタムフィールドタイプでは、独自の値の形を持つ新しいコントロールを追加します。
このガイドでは、acme/priceを最初から最後まで作成します。PHPの登録、エディターコントロール、トップレベルとリピーター内で使用する価格ブロック、厳密なRESTスキーマによる投稿メタ保存、そして表示処理を扱います。
PHPでタイプを登録する
PHP側では、属性の型、デフォルト値、コントロールを提供するエディタースクリプト、ブロック外での値の保存方法を宣言します。
add_action( 'init', function () {
wp_register_script(
'acme-field-price',
get_stylesheet_directory_uri() . '/fields/price.js',
array( 'blockstudio-blocks', 'wp-components', 'wp-element' ),
'1.0.0',
true
);
bs_register_field_type( 'acme/price', array(
'attribute' => 'object',
'default' => array(),
'editor_script' => 'acme-field-price',
'storage' => array(
'type' => 'object',
'rest_schema' => array(
'type' => 'object',
'properties' => array(
'amount' => array( 'type' => 'number', 'minimum' => 0 ),
'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
),
'additionalProperties' => false,
),
),
) );
} );
attributeはWordPress属性の型で、ここではobjectです。storage.typeはフィールドを投稿メタまたはオプションに保存するときの値の型です。storage.rest_schemaは、WordPressがRESTへの書き込みを検証するためのスキーマです。rest_schemaがない場合、オブジェクト値にはあらゆるプロパティを許可する緩やかなスキーマが適用されます。
initにデフォルトの優先度で登録してください。Blockstudioはinit上でブロックを遅れて検出するため、その時点までに登録されていないタイプは、生成されるブロック属性から除外されます。
bs_register_field_type()は成功時にtrueを返し、名前または定義が無効な場合はfalseを返します。名前は小文字、名前空間付き、ハイフン区切りである必要があり、次の2つの名前空間は予約されています。
| 名前 | 結果 |
|---|---|
acme/price |
true |
Acme/Price |
小文字ではないfalse |
custom/price |
再利用可能なフィールドグループ用に予約されたfalse |
blockstudio/price |
Blockstudioコア用に予約されたfalse |
bs_unregister_field_type()で登録を解除できます。また、blockstudio/field_typesフィルターは名前をキーとする配列で同じ定義を受け取ります。
エディターコントロールを作成する
上記で登録したスクリプトがReactコンポーネントを提供します。エディターにすでに読み込まれているWordPressコンポーネントを使うため、ビルド工程は必要ありません。
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/price', {
component(props) {
const value =
props.value && typeof props.value === 'object' && !Array.isArray(props.value)
? props.value
: {};
const currencies = props.currencies || ['EUR'];
return el(
Flex,
{ align: 'flex-end' },
el(
FlexBlock,
{},
el(TextControl, {
label: props.label,
type: 'number',
min: 0,
step: 0.01,
disabled: props.disabled,
value: value.amount ?? '',
onChange(next) {
props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
},
}),
),
el(
FlexItem,
{},
el(SelectControl, {
label: 'Currency',
hideLabelFromVision: true,
disabled: props.disabled,
value: value.currency || currencies[0],
options: currencies.map((code) => ({ label: code, value: code })),
onChange(next) {
props.onChange({ ...value, currency: next });
},
}),
),
);
},
});
コンポーネントにはフィールド定義のすべてのプロパティが渡されるため、block.jsonに指定したcurrenciesキーはprops.currenciesとして受け取れます。また、value、onChange、field、defaultValue、attributes、block、clientId、disabled、inRepeaterといった安定したpropsも受け取ります。リピーターの行内で描画される場合は、repeaterIdも渡されます。onChangeは渡された値をそのまま保存します。カスタム値には、ネイティブのselect、radio、color、gradientフィールドで適用されるオプションの正規化は行われません。
冒頭の行のように、オブジェクトでない値を扱う場合はガードしてください。フィールドが導入される前、または異なる形で保存されたブロックでも、エディターで開ける必要があります。
Blockstudioは、acme/priceを使うブロックが登録されている場合に限り、ブロックエディターでacme-field-priceを読み込みます。スクリプトでコントロールの登録に失敗すると、エディターは保存済みの値を維持し、フィールドの代わりに編集不可の通知を表示します。フロントエンドでは引き続き値が表示されます。
ブロックで使う
価格ブロックではこのタイプを2回使います。1つはブロック外からクエリできる開始価格用、もう1つは段階別価格のリピーター内の各行用です。
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/pricing",
"title": "Pricing",
"blockstudio": {
"attributes": [
{
"id": "price",
"type": "acme/price",
"label": "Starting price",
"currencies": ["EUR", "USD"],
"default": { "amount": 19, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_price"
}
},
{
"id": "tiers",
"type": "repeater",
"label": "Tiers",
"min": 0,
"max": 4,
"attributes": [
{ "id": "name", "type": "text", "label": "Name", "default": "" },
{
"id": "price",
"type": "acme/price",
"label": "Price",
"currencies": ["EUR", "USD"],
"default": { "amount": 0, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_tier_prices"
}
}
]
}
]
}
}
フィールドレベルのdefaultはレジストリのデフォルトより優先されます。Blockstudioにより、両方のフィールドが登録内容からWordPress属性になります。登録されたブロックタイプには、次の内容が含まれます。
{
"price": {
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 19, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_price" }
},
"tiers": {
"blockstudio": true,
"type": "array",
"field": "repeater",
"id": "tiers",
"attributes": [
{ "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
{
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 0, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
}
]
}
}
値を表示する
テンプレート内では、値は通常の配列です。保存値の信頼性は最後に書き込んだ処理次第なので、使う前に型を絞り込んでください。
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
if ( ! is_array( $price ) ) {
return '';
}
$amount = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';
return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
<p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
<?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
<div class="acme-tier">
<h3><?php echo esc_html( $tier['name'] ); ?></h3>
<p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
</div>
<?php endforeach; ?>
</section>
?: array()が重要です。行のないリピーターは空の配列ではなくfalseとしてテンプレートに渡されます。そのままforeachを適用するとPHP警告が発生します。@varの行については、後述の静的解析で説明します。
開始価格と2段階の価格を設定してブロックを表示します。
echo bs_block( array(
'name' => 'acme/pricing',
'data' => array(
'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
'tiers' => array(
array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
),
),
) );
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
<p>From 19.00 EUR</p>
<div class="acme-tier">
<h3>Starter</h3>
<p>19.00 EUR</p>
</div>
<div class="acme-tier">
<h3>Team</h3>
<p>49.00 EUR</p>
</div>
</section>
データがまったくない場合は、フィールドのデフォルト値が適用され、ブロックはティアなしでFrom 19.00 EURをレンダリングします。TwigとBladeはa.price.amountおよび$a['price']['amount']と同じ値を読み取り、拡張テンプレートからは{attributes.price.amount}として参照できます。
保存とRESTスキーマ
両方のフィールドはpostMeta保存を宣言しているため、Blockstudioはブロックの構築時に2つのメタキーを登録します。トップレベルのフィールドでは、登録済みの保存スキーマがそのまま使われます。
{
"type": "object",
"single": true,
"show_in_rest": {
"schema": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
リピーター内のフィールドは行ごとに1つの値を保存するため、そのメタキーは配列として保存され、同じスキーマが項目スキーマになります。
{
"type": "array",
"single": true,
"show_in_rest": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
}
このブロックを含む投稿を保存すると、両方のキーが同期されます。前述の2段階の価格の場合、get_post_meta( $id, 'acme_price', true )は{"amount":19,"currency":"EUR"}を返し、acme_tier_pricesは各行の価格リストを返します。
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
両方のキーは、投稿のRESTレスポンスのmeta内に表示され、RESTへの書き込みはスキーマに照らして検証されます。通貨コードが小文字の書き込みは拒否されます。
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
メタデータはコピーです。投稿コンテンツ内のブロック属性が元データであり、保存のたびに設定済みのキーへ再度同期されるため、メタデータに直接書き込んだ値は次回の投稿保存時に置き換えられます。オプションの保存もregister_setting()を通じて同じように行われます。リピーター内の配列ベースの保存を含むカスタムフィールド型は、Blockstudio 7.5.0以降で利用できます。
静的解析
PHPStan拡張が把握しているのは組み込みフィールドタイプであり、プロジェクトが実行時に登録するタイプは対象外です。acme/priceを使うブロックでは、フィールドタイプを不明と報告し、値をmixedとして扱います。
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
プロジェクト設定で独自タイプに関するこの診断を無視し、テンプレートでは型の絞り込みを残してください。そうすることで、PHPStanはmixed値をレベルmaxで受け入れられます。
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
この設定と上記のテンプレートを使えば、解析は通ります。7.6では、テンプレートに@varの行も必要です。カスタムフィールドの箇所にmixedを入れてください。Blockstudio7.7ではこの形が自動で推論されるため、この行は不要です。解析の実行方法はPHPStanによるテンプレートの検証を参照してください。
次のステップ
- カスタムフィールドタイプ:定義キーのすべて、APIフィルター、コンポーネントpropsの全一覧。
- 保存:あらゆるフィールドの投稿メタとオプションへの保存。
- フィールドパターンのレシピ集:グループ、リピーター、再利用可能なフィールド構造。
- カスタムフィールド:
custom/{name}による再利用可能なフィールドグループ。