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-nameverwendet 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:
{
"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:
namespace/type-name
Gültige Beispiele:
acme/dimensionsacme/text-optionstheme/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:
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:
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.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript-Registrierung
Das Editor-Skript registriert das passende React-Steuerelement:
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:
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
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
Verschachtelte Objektpfade funktionieren auch in Erweiterungs-Templates:
{
"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.
{
"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.