Перейти до вмісту

Створення власного типу поля

Деякі значення складаються з кількох примітивів. Ціна — це сума та валюта. За допомогою вбудованих полів ви моделюєте її окремими числовим полем і полем зі списком, а кожен блок із ціною повторює цю пару, мітки й логіку, що поєднує їх. У метаданих запису це перетворюється на два ключі, а в повторювачі — на два паралельні списки.

Власний тип поля об’єднує цю пару в одне поле. Ви реєструєте такий тип, як acme/price, один раз у PHP та JavaScript, а потім використовуєте його в будь-якому 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, якщо назва або визначення некоректні. Назви мають бути в нижньому регістрі, містити простір імен і складатися з частин, розділених дефісами; два простори імен зарезервовано:

Назва Результат
acme/price true
Acme/Price false, не в нижньому регістрі
custom/price false, зарезервовано для повторно використовуваних груп полів
blockstudio/price false, зарезервовано для ядра Blockstudio

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 });
          },
        }),
      ),
    );
  },
});

Компонент отримує кожну властивість визначення поля, тому ключ currencies, указаний у block.json, передається як props.currencies. Він також отримує стабільні props: value, onChange, field, defaultValue, attributes, block, clientId, disabled, inRepeater і repeaterId під час відображення в рядку повторювача. onChange зберігає значення точно в тому вигляді, у якому його передано. Власні значення пропускають нормалізацію параметрів, яку застосовують до вбудованих полів select, radio, color і gradient.

Перевіряйте, що значення є об’єктами, як це зроблено в перших рядках. Блок, збережений до появи поля або з іншою структурою, усе одно має відкриватися в редакторі.

Blockstudio додає acme-field-price до черги в редакторі блоків, лише коли зареєстровано блок, який використовує acme/price. Якщо скрипту не вдається зареєструвати елемент керування, редактор зберігає збережене значення й показує замість поля повідомлення, яке неможливо редагувати; зовнішня сторінка й далі відображає значення.

Використання в блоці

У блоці цін цей тип використовується двічі: для початкової ціни, яку потрібно запитувати поза блоком, і для кожного рядка повторювача тарифів:

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 пояснено нижче в розділі статичного аналізу.

Відображення блока з початковою ціною та двома тарифами:

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 реєструє два ключі метаданих. Для поля верхнього рівня використовується зареєстрована схема збереження без змін:

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
    }
  }
}

Поле в повторювачі зберігає одне значення для кожного рядка, тому його ключ метаданих ґрунтується на масиві, а та сама схема стає схемою елемента:

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
      }
    }
  }
}

Під час збереження запису, що містить блок, синхронізуються обидва ключі. Для двох наведених вище тарифів 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 стоять на місцях користувацьких полів; у версії 7.7 ця структура визначається автоматично, і рядок можна прибрати. Див. Перевірені шаблони з PHPStanBlockstudio, щоб запустити аналіз.

Наступні кроки