Treci la conținut

Crearea unui tip de câmp personalizat

Unele valori conțin mai mult decât un singur element primitiv. Un preț este alcătuit dintr-o sumă și o monedă. Cu câmpurile încorporate, le modelați ca un câmp numeric și unul de selectare, unul lângă altul, iar fiecare bloc care afișează un preț repetă perechea, etichetele și logica ce le ține împreună. În metadatele articolului devin două chei, iar într-un repetor, două liste paralele.

Un tip de câmp personalizat transformă perechea într-un singur câmp. Înregistrați o singură dată un tip precum acme/price în PHP și în JavaScript, apoi îl utilizați în orice block.json ca pe un câmp nativ: la nivelul superior, în grupuri și repetoare, cu stocare în metadatele articolului sau în opțiuni, precum și în șabloanele PHP, Twig și Blade. Blockstudio deduce atributul WordPress și schema de stocare REST din înregistrare.

Acesta este diferit de un câmp personalizat. O referință custom/{name} reutilizează un grup de câmpuri existente. Un tip de câmp personalizat adaugă un control nou cu propria structură a valorii.

Acest ghid construiește acme/price de la început până la sfârșit: înregistrarea PHP, controlul din editor, un bloc de prețuri care îl utilizează la nivelul superior și într-un repetor, stocarea în metadatele articolului cu o schemă REST strictă și rezultatul randat.

Înregistrarea tipului în PHP

Partea PHP declară tipul atributului, valoarea implicită, scriptul editorului care furnizează controlul și modul în care este stocată valoarea în afara blocului:

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 este tipul atributului WordPress, în acest caz object. storage.type este tipul valorii folosit când câmpul este stocat în metadatele articolului sau în opțiuni, iar storage.rest_schema este schema WordPress care validează scrierile REST. Fără o valoare rest_schema, o valoare de tip obiect primește o schemă permisivă care acceptă orice proprietăți.

Înregistrați pe init la prioritatea implicită. Blockstudio descoperă blocurile târziu, pe init, iar un tip care nu este înregistrat până atunci este omis din atributele de bloc generate.

bs_register_field_type() returnează true la succes și false dacă numele sau definiția nu sunt valide. Numele trebuie să fie cu litere mici, să aibă spațiu de nume și să folosească cratime, iar două spații de nume sunt rezervate:

Nume Rezultat
acme/price true
Acme/Price false, nu este scris cu litere mici
custom/price false, rezervat pentru grupuri de câmpuri reutilizabile
blockstudio/price false, rezervat pentru nucleul Blockstudio

bs_unregister_field_type() elimină din nou o înregistrare, iar filtrul blockstudio/field_types acceptă aceleași definiții sub forma unui tablou cu numele drept chei.

Crearea controlului din editor

Scriptul înregistrat mai sus furnizează componenta React. Aceasta utilizează componentele WordPress deja încărcate în editor, așa că nu are nevoie de un pas de compilare:

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

Componenta primește toate proprietățile definiției câmpului, astfel încât cheia currencies adăugată în block.json ajunge ca props.currencies. Primește și proprietățile stabile: value, onChange, field, defaultValue, attributes, block, clientId, disabled și inRepeater cu repeaterId atunci când se randează în interiorul unui rând de repetor. onChange stochează valoarea exact așa cum a fost furnizată. Valorile personalizate sar peste normalizarea opțiunilor aplicată de câmpurile native select, radio, color și gradient.

Protejați-vă împotriva valorilor care nu sunt obiecte, așa cum fac primele rânduri. Un bloc salvat înainte ca acel câmp să existe sau cu o structură diferită ar trebui să se deschidă în continuare în editor.

Blockstudio adaugă acme-field-price în editorul de blocuri numai când este înregistrat un bloc care folosește acme/price. Dacă scriptul nu reușește să înregistreze controlul, editorul păstrează valoarea salvată și afișează în locul câmpului o notificare care nu poate fi editată, iar partea frontală continuă să redea valoarea.

Utilizarea într-un bloc

Un bloc de prețuri utilizează tipul de două ori: o dată pentru prețul de pornire, care trebuie să poată fi interogat în afara blocului, și apoi pentru fiecare rând dintr-un repetor de niveluri:

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

O valoare default la nivel de câmp are prioritate față de valoarea implicită din registru. Blockstudio transformă ambele câmpuri în atribute WordPress pe baza înregistrării. Tipul blocului înregistrat conține:

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

Randarea valorii

În șablon, valoarea este un tablou obișnuit. Restrângeți tipul înainte de utilizare, deoarece o valoare stocată este la fel de fiabilă ca ultimul lucru care a scris-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>

Valoarea ?: array() contează. Un repetor fără rânduri ajunge în șablon ca false, nu ca tablou gol, iar folosirea directă a foreach asupra sa generează un avertisment PHP. Rândul @var este explicat mai jos, în secțiunea analiză statică.

Randarea blocului cu un preț de pornire și două niveluri:

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>

În lipsa oricăror date, se aplică valoarea implicită a câmpului, iar blocul este randat From 19.00 EUR fără niveluri. Twig și Blade citesc aceeași valoare ca a.price.amount și $a['price']['amount'], iar șabloanele extensie o pot accesa ca {attributes.price.amount}.

Stocarea și schema REST

Ambele câmpuri declară stocarea postMeta, așa că Blockstudio înregistrează două chei meta când construiește blocul. Câmpul de nivel superior utilizează ca atare schema de stocare înregistrată:

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

Câmpul din repetor stochează o valoare pentru fiecare rând, așa că cheia meta este susținută de un tablou, iar aceeași schemă devine schema elementului:

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

Salvarea unui articol care conține blocul sincronizează ambele chei. Pentru cele două niveluri de mai sus, get_post_meta( $id, 'acme_price', true ) returnează {"amount":19,"currency":"EUR"}, iar acme_tier_prices returnează lista prețurilor pe rânduri:

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

Ambele chei apar în răspunsul REST al articolului, sub meta, iar scrierile REST sunt validate conform schemei. O valoare scrisă cu moneda în litere mici este respinsă:

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

Metadatele sunt o copie. Atributele blocului din conținutul articolului rămân sursa, iar fiecare salvare le sincronizează din nou cu cheile configurate; astfel, o valoare scrisă direct în metadate este înlocuită la următoarea salvare a articolului. Stocarea în opțiuni funcționează la fel prin register_setting(). Tipurile de câmpuri personalizate, inclusiv stocarea susținută de tablouri în repetoare, sunt disponibile începând cu Blockstudio 7.5.0.

Analiza statică

Extensia PHPStan cunoaște tipurile de câmp încorporate, nu și pe cele înregistrate de un proiect la rulare. Pentru un bloc care utilizează acme/price, raportează tipul câmpului drept necunoscut și atribuie valorii tipul mixed:

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

Ignorați acel diagnostic pentru tipurile proprii din configurația proiectului și păstrați restrângerea tipului în șablon, de care PHPStan are nevoie pentru a accepta valoarea mixed la nivelul max:

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

Cu această configurație și șablonul de mai sus, analiza trece. În versiunea 7.6, șablonul are nevoie și de rândul @var, cu mixed în pozițiile câmpurilor personalizate; Blockstudio în versiunea 7.7 deduce singur acea structură, iar rândul poate fi eliminat. Consultați Șabloane verificate cu PHPStan pentru a rula analiza.

Pașii următori