コンテンツへスキップ

カスタムフィールドタイプの構築

値には単一のプリミティブでは表せないものがあります。価格は金額と通貨で構成されます。組み込みフィールドを使う場合、数値フィールドと選択フィールドを並べて表現します。価格を表示する各ブロックで、その組み合わせ、ラベル、そして両者を結び付けるロジックを繰り返すことになります。投稿メタでは2つのキーになり、リピーター内では並行する2つのリストになります。

カスタムフィールドタイプを使うと、この組み合わせを1つのフィールドにまとめられます。PHPとJavaScriptで、acme/priceのようなタイプを一度登録すれば、あとはネイティブフィールドと同じように、どのblock.jsonでも使えます。トップレベル、グループやリピーター内、投稿メタやオプションへの保存、さらにPHP、Twig、Bladeテンプレートでも利用できます。Blockstudioは登録内容からWordPress属性と保存用のRESTスキーマを導きます。

これはカスタムフィールドとは異なります。custom/{name}参照では、既存のフィールドグループを再利用します。カスタムフィールドタイプでは、独自の値の形を持つ新しいコントロールを追加します。

このガイドでは、acme/priceを最初から最後まで作成します。PHPの登録、エディターコントロール、トップレベルとリピーター内で使用する価格ブロック、厳密なRESTスキーマによる投稿メタ保存、そして表示処理を扱います。

PHPでタイプを登録する

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コンポーネントを使うため、ビルド工程は必要ありません。

JavaScript
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つは段階別価格のリピーター内の各行用です。

JSON
{
  "$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属性になります。登録されたブロックタイプには、次の内容が含まれます。

JSON
{
  "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
<?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段階の価格を設定してブロックを表示します。

PHP
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' ) ),
		),
	),
) );
HTML
<!--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つのメタキーを登録します。トップレベルのフィールドでは、登録済みの保存スキーマがそのまま使われます。

JSON
{
  "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つの値を保存するため、そのメタキーは配列として保存され、同じスキーマが項目スキーマになります。

JSON
{
  "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は各行の価格リストを返します。

JSON
[
  { "amount": 19, "currency": "EUR" },
  { "amount": 49, "currency": "EUR" }
]

両方のキーは、投稿のRESTレスポンスのmeta内に表示され、RESTへの書き込みはスキーマに照らして検証されます。通貨コードが小文字の書き込みは拒否されます。

JSON
{
  "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として扱います。

Text
  2      block.json field "price" has unknown type "acme/price" in
         blockstudio/pricing/block.json
         🪪  blockstudio.blockJson.type

プロジェクト設定で独自タイプに関するこの診断を無視し、テンプレートでは型の絞り込みを残してください。そうすることで、PHPStanはmixed値をレベルmaxで受け入れられます。

Neon
parameters:
    level: max
    ignoreErrors:
        -
            identifier: blockstudio.blockJson.type
            message: '#unknown type "acme/price"#'

この設定と上記のテンプレートを使えば、解析は通ります。7.6では、テンプレートに@varの行も必要です。カスタムフィールドの箇所にmixedを入れてください。Blockstudio7.7ではこの形が自動で推論されるため、この行は不要です。解析の実行方法はPHPStanによるテンプレートの検証を参照してください。

次のステップ