Hoppa till innehåll

Bygga en anpassad fälttyp

Vissa värden består av mer än ett primitivt värde. Ett pris är ett belopp och en valuta. Med inbyggda fält modellerar du det som ett nummerfält och ett urvalsfält bredvid varandra, och varje block som visar ett pris upprepar paret, etiketterna och logiken som håller ihop dem. I inläggsmeta blir det två nycklar och i en upprepning två parallella listor.

En anpassad fälttyp gör paret till ett enda fält. Du registrerar en typ som acme/price en gång, i PHP och i JavaScript, och använder den sedan i vilken block.json som helst som ett inbyggt fält: på toppnivå, i grupper och upprepningar, med lagring i inläggsmeta eller alternativ samt i mallar för PHP, Twig och Blade. Blockstudio härleder attributet WordPress och lagringsschemat REST från registreringen.

Det här skiljer sig från ett anpassat fält. En custom/{name}-referens återanvänder en grupp befintliga fält. En anpassad fälttyp lägger till en ny kontroll med sin egen värdestruktur.

Den här guiden bygger acme/price från början till slut: registreringen av PHP, redigerarkontrollen, ett prisblock som använder den både på toppnivå och inuti en upprepning, lagring i inläggsmeta med ett strikt REST-schema samt den renderade utdata.

Registrera typen i PHP

PHP-sidan deklarerar attributtypen, standardvärdet, redigerarskriptet som levererar kontrollen och hur värdet lagras utanför blocket:

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 är attributtypen WordPress, här object. storage.type är den värdetyp som används när fältet lagras i inläggsmeta eller alternativ, och storage.rest_schema är schemat som WordPress validerar skrivningar av REST mot. Utan en rest_schema får ett objektvärde ett tillåtande schema som godkänner alla egenskaper.

Registrera på init med standardprioritet. Blockstudio hittar block sent på init, och en typ som inte är registrerad då utelämnas från de genererade blockattributen.

bs_register_field_type() returnerar true vid framgång och false när namnet eller definitionen är ogiltig. Namn måste vara gemena, ha namnområde och använda bindestreck, och två namnområden är reserverade:

Namn Resultat
acme/price true
Acme/Price false, inte gemener
custom/price false, reserverat för återanvändbara fältgrupper
blockstudio/price false, reserverat för Blockstudio-kärnan

bs_unregister_field_type() tar bort en registrering igen, och filtret blockstudio/field_types accepterar samma definitioner som en array med nycklar efter namn.

Bygg redigerarkontrollen

Skriptet som registrerades ovan tillhandahåller komponenten React. Den använder komponenterna WordPress som redan är inlästa i redigeraren, så den behöver inget byggsteg:

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

Komponenten får alla egenskaper från fältdefinitionen, så nyckeln currencies som du anger i block.json kommer fram som props.currencies. Den får också stabila props: value, onChange, field, defaultValue, attributes, block, clientId, disabled och inRepeater, med repeaterId när den renderas inuti en upprepningsrad. onChange lagrar värdet precis som det anges. Anpassade värden hoppar över den normalisering av alternativ som inbyggda fälten select, radio, color och gradient tillämpar.

Skydda mot värden som inte är objekt, precis som de första raderna gör. Ett block som sparats innan fältet fanns, eller med en annan struktur, ska fortfarande gå att öppna i redigeraren.

Blockstudio lägger till acme-field-price i blockredigeraren endast när ett block som använder acme/price är registrerat. Om skriptet misslyckas med att registrera kontrollen behåller redigeraren det sparade värdet och visar ett meddelande som inte går att redigera i stället för fältet. Gränssnittet visar fortfarande värdet.

Använd det i ett block

Ett prisblock använder typen två gånger: en gång för ett startpris som ska kunna frågas efter utanför blocket, och en gång per rad i en upprepning med prisnivåer:

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

Ett fältvärde i default har företräde framför registerstandardvärdet. Blockstudio gör båda fälten till attribut av typen WordPress från registreringen. Den registrerade blocktypen har:

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

Rendera värdet

I mallen är värdet en vanlig array. Kontrollera dess typ innan du använder det, eftersom ett lagrat värde bara är så pålitligt som det senaste som skrev till det:

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() är viktig. En upprepning utan rader når mallen som false, inte som en tom array, och en fristående foreach över den ger en PHP-varning. Raden @var förklaras under statisk analys nedan.

Rendera blocket med ett startpris och två prisnivåer:

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>

Utan data används fältets standardvärde, och blocket renderas som From 19.00 EUR utan prisnivåer. Twig och Blade läser samma värde som a.price.amount och $a['price']['amount'], och mallar för tillägg kan adressera det som {attributes.price.amount}.

Lagring och REST-schemat

Båda fälten deklarerar lagring i postMeta, så Blockstudio registrerar två metanycklar när det bygger blocket. Toppnivåfältet använder det registrerade lagringsschemat som det är:

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

Fältet inuti upprepningen lagrar ett värde per rad, så dess metanyckel är arraybaserad och samma schema blir objektschemat:

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

När ett inlägg som innehåller blocket sparas synkas båda nycklarna. Med de två prisnivåerna ovan returnerar get_post_meta( $id, 'acme_price', true ) {"amount":19,"currency":"EUR"} och acme_tier_prices returnerar listan med radpriser:

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

Båda nycklarna visas i inläggets svar från REST under meta, och skrivningar via REST valideras mot schemat. En skrivning med en valutakod med gemener avvisas:

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

Meta är en kopia. Blockattributen i inläggsinnehållet är fortfarande källan, och varje sparning synkar dem åter till de konfigurerade nycklarna. Därför ersätts ett värde som skrivits direkt till meta nästa gång inlägget sparas. Lagring av alternativ fungerar på samma sätt via register_setting(). Anpassade fälttyper, inklusive arraybaserad lagring i upprepningar, har funnits sedan Blockstudio 7.5.0.

Statisk analys

Tillägget PHPStanextension känner till de inbyggda fälttyperna, men inte dem som ett projekt registrerar vid körning. För ett block som använder acme/price rapporterar det fälttypen som okänd och ger värdet typen mixed:

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

Ignorera diagnostiken för dina egna typer i projektkonfigurationen, och behåll typkontrollen i mallen. Den gör att PHPStan kan godta värdet mixed på nivå max:

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

Med den konfigurationen och mallen ovan går analysen igenom. I 7.6 behöver mallen också raden @var, med mixed på platserna för de anpassade fälten. I 7.7 härleder Blockstudio den strukturen på egen hand, så raden kan tas bort. Se Kontrollerade mallar med PHPStan för information om hur analysen körs.

Nästa steg