Към съдържанието

Изграждане на тип персонализирано поле

Някои стойности съдържат повече от един примитив. Цената включва сума и валута. С вградените полета я моделирате като числово поле и поле за избор едно до друго, а всеки блок, който показва цена, повтаря тази двойка, етикетите и логиката, която ги държи заедно. В метаданните на публикацията това стават два ключа, а в повтарящо се поле — два паралелни списъка.

Персонализираният тип поле превръща двойката в едно поле. Регистрирате тип като 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. Получава и стабилни свойства: 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 се валидираt спрямо схемата. Запис с валута, изписана с малки букви, се отхвърля:

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 на местата на персонализираните полета; Blockstudio 7.7 извежда тази структура автоматично и редът може da бъде премахнат. Вижте Проверени шаблони с PHPStan за изпълнението на анализа.

Следващи стъпки