Pereiti prie turinio

Pasirinktinio lauko tipo kūrimas

Kai kurios reikšmės susideda iš kelių elementarių reikšmių. Kainą sudaro suma ir valiuta. Naudojant integruotus laukus, jai pateikti reikia greta esančio skaičiaus lauko ir išskleidžiamojo sąrašo lauko, o kiekviename kainą rodančiame bloke tenka kartoti šių laukų porą, žymas ir jų sąsają užtikrinančią logiką. Įrašo meta duomenyse tai tampa dviem raktais, o kartotuve – dviem lygiagrečiais sąrašais.

Pasirinktinio lauko tipas sujungia šią porą į vieną lauką. Tipą, pavyzdžiui, acme/price, užregistruojate vieną kartą PHP ir JavaScript, o tada naudojate bet kuriame block.json kaip įprastą lauką: aukščiausiu lygiu, grupėse ir kartotuvuose, su įrašo meta duomenų arba parinkčių saugykla, taip pat šablonuose PHP, Twig ir Blade. Blockstudio pagal registraciją nustato atributą WordPress ir saugyklos schemą REST.

Tai skiriasi nuo pasirinktinio lauko. custom/{name} nuoroda pakartotinai naudoja esamų laukų grupę. Pasirinktinio lauko tipas prideda naują valdiklį su atskira reikšmės struktūra.

Šiame vadove nuosekliai sukursime acme/price: PHP registraciją, redaktoriaus valdiklį, kainos bloką, kuriame jis naudojamas aukščiausiu lygiu ir kartotuve, įrašo meta duomenų saugyklą su griežta REST schema ir atvaizduojamą rezultatą.

Užregistruokite tipą PHP

PHP dalyje deklaruojamas atributo tipas, numatytoji reikšmė, valdiklį pateikiantis redaktoriaus scenarijus ir reikšmės saugojimo ne bloke būdas:

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 yra atributo tipo WordPress reikšmė, šiuo atveju object. storage.type yra reikšmės tipas, naudojamas saugant lauką įrašo meta duomenyse arba parinktyse, o storage.rest_schema – schema, pagal kurią WordPress tikrina REST įrašomas reikšmes. Jei rest_schema nenurodyta, objekto reikšmei sukuriama lanksti schema, leidžianti bet kokias savybes.

Registruokite per init naudodami numatytąjį prioritetą. Blockstudio blokus aptinka vėliau, init, todėl tuo metu neužregistruotas tipas į sugeneruotus bloko atributus neįtraukiamas.

Sėkmingai įvykdžius bs_register_field_type() grąžina true, o jei pavadinimas arba aprašas netinkamas – false. Pavadinimai turi būti rašomi mažosiomis raidėmis, turėti vardų sritį ir brūkšniais atskirtus žodžius. Dvi vardų sritys rezervuotos:

Pavadinimas Rezultatas
acme/price true
Acme/Price false, ne mažosiomis raidėmis
custom/price false, rezervuota pakartotinai naudojamų laukų grupėms
blockstudio/price false, rezervuota Blockstudio pagrindinėms funkcijoms

bs_unregister_field_type() pašalina registraciją, o filtras blockstudio/field_types priima tuos pačius apibrėžimus kaip pagal pavadinimą indeksuotą masyvą.

Sukurkite redaktoriaus valdiklį

Pirmiau užregistruotas scenarijus pateikia komponentą React. Jame naudojami redaktoriuje jau įkelti komponentai WordPress, todėl kompiliavimo veiksmo nereikia:

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

Komponentas gauna visas lauko aprašo savybes, todėl į block.json įrašytas raktas currencies pasiekiamas kaip props.currencies. Taip pat gaunamos stabiliosios savybės: value, onChange, field, defaultValue, attributes, block, clientId, disabled ir inRepeater, o kartotuvo eilutėje atvaizduojant pridedama repeaterId. onChange tiksliai išsaugo pateiktą reikšmę. Pasirinktinių reikšmių normalizavimas pagal parinktis netaikomas, nors jį taiko integruoti laukų tipai select, radio, color ir gradient.

Kaip parodyta pirmose eilutėse, patikrinkite, ar reikšmė yra objektas. Blokas, išsaugotas dar neegzistuojant laukui arba turintis kitokią struktūrą, vis tiek turi atsidaryti redaktoriuje.

Blockstudio įtraukia acme-field-price į bloko rengyklę tik tada, kai užregistruojamas blokas, kuriame naudojamas acme/price. Jei nepavyksta užregistruoti scenarijaus, rengyklė išsaugo įrašytą reikšmę ir vietoje lauko rodo nekeičiamą pranešimą, o svetainės priekinėje dalyje reikšmė vis tiek rodoma.

Naudokite bloke

Kainos blokas šį tipą naudoja dukart: pradinei kainai, kuri turi būti pasiekiama už bloko ribų, ir kiekvienoje kainų pakopų kartotuvo eilutėje:

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

Lauko lygmens default turi pirmenybę prieš registro numatytąją reikšmę. Blockstudio abu laukus paverčia registracijoje nurodyto tipo WordPress atributais. Užregistruoto bloko tipas turi:

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

Atvaizduokite reikšmę

Šablone reikšmė yra įprastas masyvas. Prieš naudodami patikrinkite jos tipą, nes išsaugota reikšmė patikima tik tiek, kiek patikimas ją paskutinis įrašęs procesas:

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>

Svarbi ?: array() reikšmė. Kai kartotuvas neturi eilučių, šablonui pateikiama false, o ne tuščias masyvas, todėl paprastas foreach pritaikymas jam sukelia PHP įspėjimą. @var eilutė paaiškinta toliau, skiltyje statinė analizė.

Bloko atvaizdavimas su pradine kaina ir dviem pakopomis:

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>

Jei duomenų nėra, taikoma numatytoji lauko reikšmė, o blokas atvaizduojamas kaip From 19.00 EUR be kainų pakopų. Twig ir Blade nuskaito tą pačią reikšmę kaip a.price.amount ir $a['price']['amount'], o plėtinio šablonuose ją galima pasiekti kaip {attributes.price.amount}.

Saugykla ir REST schema

Abiejuose laukuose deklaruota postMeta saugykla, todėl kurdamas bloką Blockstudio užregistruoja du meta raktus. Aukščiausio lygio lauke naudojama užregistruota saugyklos schema tokia, kokia yra:

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

Kartotuvo lauke saugoma po vieną reikšmę kiekvienai eilutei, todėl jo meta raktas pagrįstas masyvu, o ta pati schema tampa elemento schema:

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

Išsaugojus įrašą su šiuo bloku, sinchronizuojami abu raktai. Esant pirmiau nurodytoms dviem pakopoms, get_post_meta( $id, 'acme_price', true ) grąžina {"amount":19,"currency":"EUR"}, o acme_tier_prices grąžina eilučių kainų sąrašą:

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

Abu raktai matomi įrašo atsakyme REST, po raktu meta, o įrašymo operacijos REST tikrinamos pagal schemą. Įrašyti valiutą mažosiomis raidėmis neleidžiama:

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

Meta duomenys yra kopija. Bloko atributų šaltinis lieka įrašo turinys, ir kiekvieną kartą išsaugant jie vėl sinchronizuojami su sukonfigūruotais raktais, todėl tiesiogiai į meta įrašyta reikšmė pakeičiama kitą kartą išsaugant įrašą. Parinkčių saugykla veikia taip pat per register_setting(). Pasirinktiniai laukų tipai, įskaitant masyvais pagrįstą saugojimą kartotuvuose, prieinami nuo Blockstudio 7.5.0 versijos.

Statinė analizė

PHPStan plėtinys atpažįsta integruotų laukų tipus, bet ne tuos, kuriuos projektas užregistruoja vykdymo metu. Bloke, kuriame naudojamas acme/price, jis nurodo, kad lauko tipas nežinomas, o jo reikšmės tipą nustato kaip mixed:

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

Projekto konfigūracijoje nekreipkite dėmesio į šią diagnostikos žinutę, skirtą jūsų tipams, bet šablone palikite tipo tikrinimą. Jo reikia, kad PHPStan priimtų mixed reikšmę, kurios lygis yra max:

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

Nurodžius šią konfigūraciją ir pirmiau pateiktą šabloną, analizė sėkmingai vykdoma. 7.6 versijoje šablonui dar reikia eilutės @var; mixed vietose nurodomi pasirinktiniai laukai. Nuo 7.7 versijos Blockstudio pats nustato šią struktūrą, todėl eilutę galima pašalinti. Kaip vykdyti analizę, žr. Tikrinami šablonai su PHPStan.

Tolesni veiksmai