Zum Inhalt springen

Benutzerdefinierte Feldtypen

Benutzerdefinierte Feldtypen ermöglichen es Themes oder Plugins, neue Blockstudio-Feldsteuerelemente hinzuzufügen. Sie unterscheiden sich von benutzerdefinierten Feldern:

  • custom/{name} verweist auf eine wiederverwendbare Gruppe vorhandener Felder.
  • namespace/type-name verwendet einen registrierten Feldtyp mit eigenem Editor-Steuerelement und eigener Wertstruktur.

Blockstudio stellt das Registrierungssystem bereit. Dein Theme oder Plugin stellt das Steuerelement bereit.

Wann du sie verwendest

Verwende einen benutzerdefinierten Feldtyp, wenn ein Projekt ein spezielles Bearbeitungs-Steuerelement benötigt, das sich überall wie ein natives Blockstudio-Feld verhalten soll:

  • Blockattribute
  • wiederverwendbare custom/{name}-Feldgruppen
  • Gruppen, Tabs und Repeater
  • PHP-, Twig- und Blade-Templates
  • Beitragsmetadaten und Optionenspeicherung
  • Erweiterungs-Templates wie {attributes.margin.top}

Ein Abstands-Steuerelement kann beispielsweise ein Objekt statt vier separater Textfelder speichern:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Namensgebung

Namen benutzerdefinierter Feldtypen müssen kleingeschrieben, mit Namespace versehen und im dashcase-Format sein:

Text
namespace/type-name

Gültige Beispiele:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Reservierte Namespaces:

  • custom/ ist für wiederverwendbare benutzerdefinierte Feldgruppen reserviert.
  • blockstudio/ ist für den Blockstudio-Kern reserviert.

Ungültige Namen werden vom Filter API ignoriert und vom Hilfsprogramm API abgelehnt.

PHP-Registrierung

Registriere die Metadaten des Feldtyps in PHP:

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});

bs_register_field_type() gibt bei erfolgreicher Registrierung true zurück und false, wenn der Name oder die Definition ungültig ist. Eine manuelle Registrierung kannst du mit bs_unregister_field_type() aufheben.

Du kannst auch den Filter API verwenden:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

Definitionsschlüssel

Schlüssel Typ Beschreibung
attribute string, array, null WordPress-Attributtyp. Verwende string, number, boolean, object, array oder ein Array dieser Typen.
default mixed Standardwert auf Registry-Ebene, wenn ein Feld keinen eigenen Standardwert definiert.
source string WordPress-Attributquelle für benutzerdefinierte Serialisierungsfälle.
produces_attribute boolean Auf false setzen für Steuerelemente, die nur der Anzeige dienen. Standardmäßig true.
editor_script string or array Registrierter Skript-Handle bzw. registrierte Skript-Handles, die im Block-Editor geladen werden, wenn der Typ verwendet wird.
editor_style string or array Registrierter Stil-Handle bzw. registrierte Stil-Handles, die im Block-Editor geladen werden, wenn der Typ verwendet wird.
storage array Hinweise zum Speichertyp und Schema REST für Beitragsmetadaten und Optionen.
supports array Optionale Fähigkeitsmerkmale für dein eigenes Steuerelement.
translate boolean Auf true setzen, wenn der Wert Text ist, den WPML übersetzen soll. Erfordert attribute string.

Eine Definition mit einem translate-Wert, der kein Boolean ist, oder mit translate auf true und einem attribute, das nicht string ist, ist ungültig. bs_register_field_type() gibt false zurück, und der Filter API ignoriert sie.

WPML

wp bs wpml config kann anhand der Registrierung allein nicht erkennen, ob der Wert eines benutzerdefinierten Feldtyps Text ist. Daher lässt es solche Felder aus und gibt für jedes eine Warnung aus. Setze translate bei der Registrierung eines Feldtyps, der eine einfache Textzeichenfolge speichert, auf true. Dann deklariert der Befehl seine Felder wie text-Felder. Ein Feld kann dies weiterhin mit "translate": false deaktivieren. Weitere Informationen findest du unter WPMLDokumentation zu portablen Medienreferenzen.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

JavaScript-Registrierung

Das Editor-Skript registriert das passende React-Steuerelement:

JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

registerFieldType() gibt true zurück, wenn die Registrierung angenommen wird. Entferne eine clientseitige Registrierung mit:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

Die Komponente erhält die Eigenschaften der Felddefinition sowie diese stabilen Props:

Prop Beschreibung
type Feldtypname.
id Feld-ID.
field Vollständige Felddefinition aus block.json.
value Aktuell gespeicherter Wert.
defaultValue Standardwert des Felds.
onChange Direkt einen neuen Wert speichern.
attributes Aktuelle Blockattribute.
block Aktuelle Blocktypdefinition.
clientId Client-ID des aktuellen Editor-Blocks.
inRepeater Gibt an, ob sich das Feld in einer Repeater-Zeile befindet.
repeaterId Aktueller Repeater-Pfad, falls vorhanden.
disabled Gibt an, ob das Feld im Editor deaktiviert ist.

Werte benutzerdefinierter Feldtypen werden direkt gespeichert. Sie durchlaufen keine native Normalisierung von Optionen durch select, radio, color oder gradient.

Werte rendern

Objektwerte sind wie jedes andere Blockstudio-Attribut verfügbar.

PHP

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

Verschachtelte Objektpfade funktionieren auch in Erweiterungs-Templates:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Speicherung

Wird ein benutzerdefinierter Feldtyp mit postMeta– oder option-Speicherung verwendet, nutzt Blockstudio den registrierten Speicherdatentyp und das registrierte REST-Schema.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

Definiere für array– und object-Werte storage.rest_schema in der Feldtypregistrierung. Nachfahren von Repeatern verwenden weiterhin Array-Speicherung, da ein Repeater Zeilen speichert.

Verhalten bei fehlender Registrierung

Wenn PHP den Feldtyp kennt, das Editor-Skript aber kein passendes Steuerelement registriert, behält Blockstudio den gespeicherten Wert bei und zeigt im Editor einen Hinweis an, der nicht bearbeitet werden kann. Beim Rendern im Frontend steht der gespeicherte Wert weiterhin zur Verfügung.

Wenn ein Feldtyp nicht in PHP registriert ist, lässt Blockstudio ihn aus den generierten WordPress-Attributen aus. Registriere die Definition von PHP, bevor die Blockerkennung ausgeführt wird, normalerweise in init, bevor Blockstudio Blöcke erstellt.