Brugerdefinerede felttyper
Brugerdefinerede felttyper lader et tema eller plugin tilføje nye Blockstudio-feltkontroller. De er forskellige fra brugerdefinerede felter:
custom/{name}henviser til en genanvendelig gruppe af eksisterende felter.namespace/type-namebruger en registreret felttype med sin egen redigeringskontrol og værdistruktur.
Blockstudio leverer registreringssystemet. Dit tema eller plugin leverer kontrollen.
Hvornår skal de bruges
Brug en brugerdefineret felttype, når et projekt har brug for en specialiseret redigeringskontrol, der skal fungere som et indbygget Blockstudio-felt overalt:
- blokattributter
- genanvendelige
custom/{name}-feltgrupper - grupper, faner og repeatere
- PHP-, Twig- og Blade-skabeloner
- lagring af indlægsmetadata og indstillinger
- udvidelsesskabeloner som
{attributes.margin.top}
For eksempel kan en afstandskontrol gemme ét objekt i stedet for fire separate tekstfelter:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Navngivning
Navne på brugerdefinerede felttyper skal være med små bogstaver, have et navnerum og bruge bindestreger:
namespace/type-name
Gyldige eksempler:
acme/dimensionsacme/text-optionstheme/spacing-token
Reserverede navnerum:
custom/er reserveret til genanvendelige brugerdefinerede feltgrupper.blockstudio/er reserveret til Blockstudio-kernen.
Ugyldige navne ignoreres af filteret API og afvises af hjælpefunktionen API.
Registrering af PHP
Registrer felttypens metadata i 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() returnerer true, når registreringen lykkes, og false, når navnet eller definitionen er ugyldig. Du kan fjerne en manuel registrering med bs_unregister_field_type().
Du kan også bruge filteret API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Definitionsnøgler
| Nøgle | Type | Beskrivelse |
|---|---|---|
attribute |
string, array, null |
WordPress attributtype. Brug string, number, boolean, object, array eller et array af disse typer. |
default |
mixed | Standardværdi på registreringsniveau, når et felt ikke definerer sin egen standardværdi. |
source |
string | WordPress attributkilde til brugerdefinerede serialiseringstilfælde. |
produces_attribute |
boolean | Sæt til false for kontrolelementer, der kun viser indhold. Standardværdien er true. |
editor_script |
string or array | Registreret script-handle eller handles, der skal indlæses i blokeditoren, når typen bruges. |
editor_style |
string or array | Registreret stil-handle eller handles, der skal indlæses i blokeditoren, når typen bruges. |
storage |
array | Lagerets værditype og REST skemahints til postmeta og indstillinger. |
supports |
array | Valgfrie kapabilitetsflag til dit eget kontrolelement. |
translate |
boolean | Sæt til true, når værdien er tekst, som WPML skal oversætte. Kræver attribute string. |
En definition med en translate-værdi, der ikke er en boolean, eller med
translate sat til true og en attribute, der ikke er string, er ugyldig.
bs_register_field_type() returnerer false, og filteret API ignorerer den.
WPML
wp bs wpml config kan ikke ud fra registreringen alene afgøre, om værdien
for en brugerdefineret felttype er tekst, så sådanne felter udelades, og der vises en
advarsel for hvert felt. Sæt translate til true i registreringen af en felttype,
der gemmer en almindelig tekststreng, så erklærer kommandoen felterne som
text-felter. Et felt kan stadig fravælges med "translate": false. Se
WPMLbærbare mediehenvisninger.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registrering af JavaScript
Editorscriptet registrerer den tilhørende React-kontrol:
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() returnerer true, når registreringen godkendes. Fjern en klientregistrering med:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponenten modtager feltddefinitionens egenskaber samt disse stabile props:
| Prop | Beskrivelse |
|---|---|
type |
Felttypens navn. |
id |
Felt-ID. |
field |
Fuldstændig feltdefinition fra block.json. |
value |
Aktuel gemt værdi. |
defaultValue |
Feltets standardværdi. |
onChange |
Gem en ny værdi direkte. |
attributes |
Aktuelle blokattributter. |
block |
Aktuel bloktypeddefinition. |
clientId |
Aktuelt klient-ID for editorblokken. |
inRepeater |
Om feltet er inde i en repeaterrække. |
repeaterId |
Aktuel repeatersti, hvis der er en. |
disabled |
Om feltet er deaktiveret i editoren. |
Værdier for brugerdefinerede felttyper gemmes direkte. De gennemgår ikke normalisering af indstillinger for indbyggede select, radio, color eller gradient.
Gengivelse af værdier
Objektværdier er tilgængelige som alle andre Blockstudio-attributter.
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>
Indlejrede objektstier fungerer også i udvidelsesskabeloner:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Lagring
Når en brugerdefineret felttype bruges med lagring i postMeta eller option, bruger Blockstudio den registrerede lagringsværditype og REST-skemaet.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
For værdier af typen array og object skal du definere storage.rest_schema ved registrering af felttypen. Repeaterens underordnede felter fortsætter med at bruge arraybaseret lagring, fordi en repeater gemmer rækker.
Reserveadfærd
Hvis PHP kender felttypen, men editorscriptet ikke registrerer en tilsvarende kontrol, bevarer Blockstudio den gemte værdi og viser en ikke-redigerbar besked i editoren. Frontend-gengivelse modtager stadig den gemte værdi.
Hvis en felttype ikke er registreret i PHP, udelader Blockstudio den fra de genererede WordPress-attributter. Registrer PHP-definitionen, før blokregistreringen køres, normalt på init før Blockstudio bygger blokke.