Przejdź do treści

Tworzenie własnego typu pola

Niektóre wartości składają się z czegoś więcej niż jeden typ prosty. Cena obejmuje kwotę i walutę. Przy wbudowanych polach modelujesz ją za pomocą pola liczbowego i pola wyboru umieszczonych obok siebie. Każdy blok wyświetlający cenę powiela tę parę, etykiety oraz logikę, która je łączy. W metadanych wpisu cena staje się dwoma kluczami, a w repeaterze — dwiema równoległymi listami.

Własny typ pola łączy tę parę w jedno pole. Rejestrujesz typ, taki jak acme/price, raz w PHP i w JavaScript, a następnie używasz go w dowolnym block.json jak pola wbudowanego: na najwyższym poziomie, w grupach i repeaterach, z zapisem w metadanych wpisu lub opcjach, a także w szablonach PHP, Twig i Blade. Blockstudio wyprowadza atrybut WordPress i schemat przechowywania REST na podstawie rejestracji.

To coś innego niż własne pole. Odwołanie custom/{name} ponownie wykorzystuje grupę istniejących pól. Własny typ pola dodaje nową kontrolkę z własnym formatem wartości.

Ten przewodnik opisuje cały proces tworzenia acme/price: rejestrację PHP, kontrolkę edytora, blok z cenami używający jej na najwyższym poziomie i w repeaterze, zapis w metadanych wpisu z rygorystycznym schematem REST oraz renderowanie wyniku.

Rejestrowanie typu w PHP

Część PHP określa typ atrybutu, wartość domyślną, skrypt edytora dostarczający kontrolkę oraz sposób przechowywania wartości poza blokiem:

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 to typ atrybutu WordPress, tutaj object. storage.type to typ wartości używany, gdy pole jest przechowywane w metadanych wpisu lub opcjach, a storage.rest_schema to schemat, według którego WordPress sprawdza zapisy REST. Bez rest_schema wartość obiektu otrzymuje liberalny schemat, który akceptuje dowolne właściwości.

Zarejestruj typ w init z domyślnym priorytetem. Blockstudio wykrywa bloki późno na init, a typ, który nie zostanie do tego czasu zarejestrowany, nie trafia do generowanych atrybutów bloków.

bs_register_field_type() zwraca true w razie powodzenia i false, gdy nazwa lub definicja jest nieprawidłowa. Nazwy muszą być zapisane małymi literami, mieć przestrzeń nazw i łączniki; dwie przestrzenie nazw są zarezerwowane:

Nazwa Wynik
acme/price true
Acme/Price false, nie jest zapisana małymi literami
custom/price false, zarezerwowana dla grup pól wielokrotnego użytku
blockstudio/price false, zarezerwowana dla rdzenia Blockstudio

bs_unregister_field_type() ponownie usuwa rejestrację, a filtr blockstudio/field_types przyjmuje te same definicje jako tablicę indeksowaną nazwami.

Tworzenie kontrolki edytora

Zarejestrowany wyżej skrypt udostępnia komponent React. Korzysta on z komponentów WordPress już załadowanych w edytorze, więc nie wymaga kompilacji:

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

Komponent otrzymuje wszystkie właściwości definicji pola, więc klucz currencies umieszczony w block.json jest dostępny jako props.currencies. Otrzymuje też stabilne właściwości: value, onChange, field, defaultValue, attributes, block, clientId, disabled i inRepeater wraz z repeaterId, gdy renderuje się wewnątrz wiersza repeatera. onChange zapisuje wartość dokładnie w podanej postaci. Własne wartości pomijają normalizację opcji stosowaną przez wbudowane pola select, radio, color i gradient.

Zabezpiecz się przed wartościami, które nie są obiektami, tak jak w pierwszych liniach przykładu. Blok zapisany przed dodaniem pola lub z inną strukturą nadal powinien otwierać się w edytorze.

Blockstudio dodaje do kolejki acme-field-price w edytorze bloków tylko wtedy, gdy zarejestrowano blok korzystający z acme/price. Jeśli skrypt nie zarejestruje kontrolki, edytor zachowuje zapisaną wartość i wyświetla zamiast pola nieedytowalne powiadomienie; frontend nadal renderuje wartość.

Używanie pola w bloku

Blok z cenami używa tego typu dwukrotnie: raz dla ceny początkowej, którą trzeba udostępnić do wyszukiwania poza blokiem, i raz dla każdego wiersza repeatera z progami cenowymi:

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

Wartość default na poziomie pola ma pierwszeństwo przed domyślną wartością rejestru. Blockstudio zmienia oba pola w atrybuty WordPress na podstawie rejestracji. Zarejestrowany typ bloku ma następujące właściwości:

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

Renderowanie wartości

W szablonie wartość jest zwykłą tablicą. Przed użyciem zawęź jej typ, ponieważ zaufanie do zapisanej wartości zależy od tego, co ją ostatnio zapisało:

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>

Znaczenie ma ?: array(). Repeater bez wierszy trafia do szablonu jako false, a nie jako pusta tablica, a zwykłe foreach na tej wartości powoduje ostrzeżenie PHP. Wyjaśnienie wiersza @var znajduje się poniżej w części analiza statyczna.

Renderowanie bloku z ceną początkową i dwoma progami:

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>

Gdy nie ma żadnych danych, stosowana jest domyślna wartość pola, a blok renderuje From 19.00 EUR bez progów cenowych. Twig i Blade odczytują tę samą wartość co a.price.amount i $a['price']['amount'], a szablony rozszerzenia szablonów mogą odwołać się do niej jako do {attributes.price.amount}.

Zapis i schemat REST

Oba pola deklarują zapis postMeta, więc Blockstudio rejestruje podczas tworzenia bloku dwa klucze meta. Pole na najwyższym poziomie używa zarejestrowanego schematu zapisu bez zmian:

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

Pole wewnątrz repeatera zapisuje jedną wartość w każdym wierszu, więc jego klucz meta jest oparty na tablicy, a ten sam schemat staje się schematem elementu:

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

Zapisanie wpisu zawierającego blok synchronizuje oba klucze. Przy dwóch progach cenowych z przykładu get_post_meta( $id, 'acme_price', true ) zwraca {"amount":19,"currency":"EUR"}, a acme_tier_prices zwraca listę cen wierszy:

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

Oba klucze pojawiają się w odpowiedzi REST wpisu pod meta, a zapisy REST są sprawdzane według schematu. Zapis waluty małymi literami zostanie odrzucony:

JSON
{
  "code": "rest_invalid_pattern",
  "message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
  "data": { "status": 400 }
}

Metadane są kopią. Atrybuty bloków w treści wpisu pozostają źródłem danych, a każdy zapis ponownie synchronizuje je ze skonfigurowanymi kluczami. Dlatego wartość zapisana bezpośrednio w metadanych zostanie zastąpiona przy następnym zapisaniu wpisu. Zapis w opcjach działa tak samo przez register_setting(). Własne typy pól, w tym zapis oparty na tablicy wewnątrz repeaterów, są dostępne od wersji Blockstudio 7.5.0.

Analiza statyczna

Rozszerzenie PHPStan zna wbudowane typy pól, ale nie te rejestrowane przez projekt w czasie działania. W bloku korzystającym z acme/price zgłasza nieznany typ pola i określa typ jego wartości jako mixed:

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

Zignoruj ten komunikat dla własnych typów w konfiguracji projektu, ale pozostaw zawężanie typu w szablonie — jest ono potrzebne, aby PHPStan zaakceptował wartość mixed na poziomie max:

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

Przy tej konfiguracji i powyższym szablonie analiza przechodzi poprawnie. W wersji 7.6 szablon wymaga też wiersza @var z mixed w miejscach pól własnych. Od wersji 7.7 Blockstudio samodzielnie wywnioskuje tę strukturę i wiersz można usunąć. Informacje o uruchamianiu analizy znajdziesz w Szablonach sprawdzanych za pomocą PHPStan.

Następne kroki

  • Własne typy pól: wszystkie klucze definicji, filtr API i pełna lista właściwości komponentu.
  • Zapis: zapis dowolnego pola w metadanych wpisu i opcjach.
  • Zbiór wzorców pól: grupy, repeatery i struktury pól wielokrotnego użytku.
  • Pola własne: grupy pól wielokrotnego użytku za pomocą custom/{name}.