Zum Inhalt springen

Einen benutzerdefinierten Feldtyp erstellen

Manche Werte bestehen aus mehr als einem einfachen Datentyp. Ein Preis umfasst einen Betrag und eine Währung. Mit integrierten Feldern modellierst du ihn als Zahlenfeld neben einem Auswahlfeld. Jeder Block, der einen Preis anzeigt, wiederholt dieses Paar, die Beschriftungen und die Logik, die beides zusammenhält. In Post-Meta werden daraus zwei Schlüssel und in einem Wiederholfeld zwei parallele Listen.

Ein benutzerdefinierter Feldtyp fasst das Paar in einem Feld zusammen. Du registrierst einen Typ wie acme/price einmalig in PHP und in JavaScript und verwendest ihn anschließend in jedem block.json wie ein natives Feld: auf oberster Ebene, in Gruppen und Wiederholfeldern, mit Post-Meta- oder Optionsspeicherung sowie in PHP-, Twig- und Blade-Vorlagen. Blockstudio leitet das Attribut WordPress und das Speicherschema REST aus der Registrierung ab.

Das unterscheidet sich von einem benutzerdefinierten Feld. Eine custom/{name}-Referenz verwendet eine Gruppe bestehender Felder erneut. Ein benutzerdefinierter Feldtyp fügt ein neues Steuerelement mit eigener Wertstruktur hinzu.

Diese Anleitung erstellt acme/price von Anfang bis Ende: die Registrierung PHP, das Editor-Steuerelement, einen Preisblock, der den Typ auf oberster Ebene und in einem Wiederholfeld verwendet, die Speicherung in Post-Meta mit strengem REST-Schema und die gerenderte Ausgabe.

Den Typ in PHP registrieren

Der Teil PHP legt den Attributtyp, den Standardwert, das Editor-Skript für das Steuerelement und die Speicherung des Werts außerhalb des Blocks fest:

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 ist der Attributtyp WordPress, hier object. storage.type ist der Werttyp, der verwendet wird, wenn das Feld in Beitragsmetadaten oder Optionen gespeichert wird. storage.rest_schema ist das Schema, gegen das WordPress Schreibvorgänge von REST validiert. Ohne rest_schema erhält ein Objektwert ein großzügiges Schema, das beliebige Eigenschaften akzeptiert.

Registriere den Typ auf init mit der Standardpriorität. Blockstudio erkennt Blöcke spät auf init. Ein Typ, der bis dahin nicht registriert ist, wird aus den generierten Blockattributen ausgelassen.

bs_register_field_type() gibt bei Erfolg true und bei ungültigem Namen oder ungültiger Definition false zurück. Namen müssen kleingeschrieben, namensraumgebunden und im Dash-Format sein; zwei Namensräume sind reserviert:

Name Ergebnis
acme/price true
Acme/Price false, nicht kleingeschrieben
custom/price false, für wiederverwendbare Feldgruppen reserviert
blockstudio/price false, für den Blockstudio-Kern reserviert

bs_unregister_field_type() hebt eine Registrierung wieder auf, und der Filter blockstudio/field_types akzeptiert dieselben Definitionen als nach Namen indiziertes Array.

Editor-Steuerelement erstellen

Das oben registrierte Skript stellt die Komponente React bereit. Sie verwendet die bereits im Editor geladenen Komponenten WordPress und benötigt daher keinen Build-Schritt:

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

Die Komponente erhält sämtliche Eigenschaften der Felddefinition. Der Schlüssel currencies, den du in block.json einfügst, kommt also als props.currencies an. Außerdem erhält sie stabile Props: value, onChange, field, defaultValue, attributes, block, clientId, disabled und inRepeater mit repeaterId, wenn sie in einer Wiederholfeld-Zeile gerendert wird. onChange speichert den Wert genau so, wie er übergeben wurde. Benutzerdefinierte Werte durchlaufen nicht die Normalisierung von Optionen, die native Felder select, radio, color und gradient anwenden.

Sichere dich wie in den ersten Zeilen gegen Werte ab, die keine Objekte sind. Ein Block, der vor dem Feld oder mit einer anderen Struktur gespeichert wurde, sollte sich weiterhin im Editor öffnen lassen.

Blockstudio bindet acme-field-price nur dann im Block-Editor ein, wenn ein Block registriert ist, der acme/price verwendet. Kann das Skript das Steuerelement nicht registrieren, behält der Editor den gespeicherten Wert und zeigt anstelle des Felds einen nicht bearbeitbaren Hinweis an. Im Frontend wird der Wert weiterhin gerendert.

In einem Block verwenden

Ein Preisblock verwendet den Typ zweimal: einmal für einen Startpreis, der außerhalb des Blocks abgefragt werden soll, und einmal pro Zeile eines Wiederholfelds für Preisstufen:

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

Ein Feldwert für default hat Vorrang vor dem Standardwert der Registrierung. Blockstudio macht beide Felder zu WordPress-Attributen aus der Registrierung. Der registrierte Blocktyp enthält:

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

Wert rendern

In der Vorlage ist der Wert ein gewöhnliches Array. Prüfe den Typ, bevor du ihn verwendest, denn ein gespeicherter Wert ist nur so vertrauenswürdig wie der letzte Schreibvorgang:

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() ist wichtig. Ein Wiederholfeld ohne Zeilen kommt in der Vorlage als false an, nicht als leeres Array. Eine einfache foreach-Schleife darüber löst eine Warnung PHP aus. Die Zeile @var wird weiter unten im Abschnitt Statische Analyse erklärt.

Den Block mit einem Startpreis und zwei Preisstufen rendern:

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>

Ohne Daten greift der Standardwert des Feldes, und der Block wird mit From 19.00 EUR und ohne Preisstufen gerendert. Twig und Blade lesen denselben Wert als a.price.amount und $a['price']['amount']. Vorlagen von extension können darauf als {attributes.price.amount} zugreifen.

Speicherung und das Schema REST

Beide Felder deklarieren die Speicherung postMeta. Daher registriert Blockstudio beim Erstellen des Blocks zwei Meta-Schlüssel. Das Feld auf oberster Ebene verwendet das registrierte Speicherschema unverändert:

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

Das Feld im Wiederholfeld speichert einen Wert pro Zeile. Sein Meta-Schlüssel basiert daher auf einem Array, und dasselbe Schema wird zum Schema der einzelnen Elemente:

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

Beim Speichern eines Beitrags mit diesem Block werden beide Schlüssel synchronisiert. Mit den beiden Preisstufen von oben gibt get_post_meta( $id, 'acme_price', true ) {"amount":19,"currency":"EUR"} zurück, und acme_tier_prices gibt die Liste der Zeilenpreise zurück:

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

Beide Schlüssel erscheinen in der REST-Antwort des Beitrags unter meta, und Schreibvorgänge mit REST werden gegen das Schema validiert. Ein Schreibvorgang mit einer kleingeschriebenen Währungsangabe wird abgelehnt:

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

Meta ist eine Kopie. Die Blockattribute im Beitragsinhalt bleiben die Quelle und werden bei jedem Speichern erneut mit den konfigurierten Schlüsseln synchronisiert. Ein direkt in Meta geschriebener Wert wird daher beim nächsten Speichern des Beitrags ersetzt. Die Speicherung in Optionen funktioniert über register_setting() genauso. Benutzerdefinierte Feldtypen, einschließlich der Speicherung in arraybasierten Wiederholfeldern, sind ab Blockstudio 7.5.0 verfügbar.

Statische Analyse

Die PHPStan-Erweiterung kennt integrierte Feldtypen, aber keine, die ein Projekt zur Laufzeit registriert. Bei einem Block mit acme/price meldet sie den Feldtyp als unbekannt und typisiert den Wert als mixed:

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

Ignoriere diese Diagnose für eigene Typen in der Projektkonfiguration und behalte die Typprüfung in der Vorlage bei. So kann PHPStan den Wert mixed auf Stufe max akzeptieren:

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

Mit dieser Konfiguration und der Vorlage von oben ist die Analyse erfolgreich. Unter Version 7.6 braucht die Vorlage außerdem die Zeile @var, wobei mixed an den Stellen der benutzerdefinierten Felder steht. Ab Version Blockstudio 7.7 leitet sie diese Struktur selbst her, sodass die Zeile entfallen kann. In Vorlagen mit PHPStan prüfen erfährst du, wie du die Analyse ausführst.

Nächste Schritte