Anpassade fälttyper
Med anpassade fälttyper kan ett tema eller tillägg lägga till nya Blockstudio-fältkontroller. De skiljer sig från anpassade fält:
custom/{name}refererar till en återanvändbar grupp med befintliga fält.namespace/type-nameanvänder en registrerad fälttyp med en egen redigeringskontroll och värdestruktur.
Blockstudio tillhandahåller registreringssystemet. Ditt tema eller tillägg tillhandahåller kontrollen.
När du ska använda dem
Använd en anpassad fälttyp när ett projekt behöver en redigeringskontroll med ett enda syfte som ska fungera som ett inbyggt Blockstudio-fält överallt:
- blockattribut
- återanvändbara
custom/{name}-fältgrupper - grupper, flikar och repeaters
- mallar för PHP, Twig och Blade
- lagring av metadata för inlägg och alternativ
- tilläggsmallar som
{attributes.margin.top}
En mellanrumskontroll kan till exempel lagra ett objekt i stället för fyra separata textfält:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Namngivning
Namn på anpassade fälttyper måste bestå av gemener, ha ett namnområde och använda bindestreck:
namespace/type-name
Giltiga exempel:
acme/dimensionsacme/text-optionstheme/spacing-token
Reserverade namnområden:
custom/är reserverat för återanvändbara anpassade fältgrupper.blockstudio/är reserverat för kärnan i Blockstudio.
Ogiltiga namn ignoreras av filtret API och avvisas av hjälpfunktionen API.
PHP-registrering
Registrera metadata för fälttypen 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() returnerar true om registreringen lyckas och false om namnet eller definitionen är ogiltig. Du kan avregistrera en manuell registrering med bs_unregister_field_type().
Du kan också använda filtret API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Definitionsnycklar
| Nyckel | Typ | Beskrivning |
|---|---|---|
attribute |
string, array, null |
Attributtyp för WordPress. Använd string, number, boolean, object, array eller en array med dessa typer. |
default |
mixed | Standardvärde på registernivå när ett fält inte har ett eget standardvärde. |
source |
string | Attributkälla för anpassade serialiseringsfall: WordPress. |
produces_attribute |
boolean | Ange false för kontroller som endast visar information. Standardvärdet är true. |
editor_script |
string or array | Registrerat skripthandtag eller registrerade skripthandtag som ska köas i blockredigeraren när typen används. |
editor_style |
string or array | Registrerat stilhandtag eller registrerade stilhandtag som ska köas i blockredigeraren när typen används. |
storage |
array | Lagringsvärdets typ och REST-schematips för inläggsmeta och alternativ. |
supports |
array | Valfria kapabilitetsflaggor för din egen kontroll. |
translate |
boolean | Ange true när värdet är text som WPML ska översätta. Kräver attribute string. |
En definition med ett translate-värde som inte är en boolean, eller med translate satt till true och ett attribute annat än string, är ogiltig.
bs_register_field_type() returnerar false och filtret API ignorerar den.
WPML
wp bs wpml config kan inte avgöra enbart utifrån registreringen om värdet för en anpassad fälttyp är text, så sådana fält utelämnas och en varning skrivs ut för varje fält. Ange translate till true i registreringen av en fälttyp som lagrar en vanlig textsträng, så deklarerar kommandot dess fält som text-fält. Ett fält kan fortfarande välja att inte delta med "translate": false. Se WPMLbärbara medierreferenser.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript-registrering
Redigerarskriptet registrerar motsvarande React-kontroll:
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() returnerar true när registreringen godkänns. Ta bort en klientregistrering med:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponenten tar emot egenskaperna från fältdefinitionen samt dessa beständiga egenskaper:
| Egenskap | Beskrivning |
|---|---|
type |
Fälttypens namn. |
id |
Fält-ID. |
field |
Fullständig fältdefinition från block.json. |
value |
Aktuellt sparat värde. |
defaultValue |
Fältets standardvärde. |
onChange |
Spara ett nytt värde direkt. |
attributes |
Aktuella blockattribut. |
block |
Aktuell blocktypdefinition. |
clientId |
Aktuellt klient-ID för redigerarblocket. |
inRepeater |
Anger om fältet ligger i en repeaterad. |
repeaterId |
Aktuell repeater-sökväg, om det finns någon. |
disabled |
Anger om fältet är inaktiverat i redigeraren. |
Värden för anpassade fälttyper lagras direkt. De passerar inte genom normalisering av inbyggda alternativ i select, radio, color eller gradient.
Återgivning av värden
Objektvärden är tillgängliga precis som alla andra Blockstudio-attribut.
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>
Kapslade objektsökvägar fungerar också i tilläggsmallar:
{
"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 anpassad fälttyp används med lagringen postMeta eller option använder Blockstudio den registrerade lagringsvärdestypen och schemat REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
För värdena array och object definierar du storage.rest_schema i fälttypens registrering. Underordnade repeaterfält fortsätter att använda arraybaserad lagring eftersom en repeater lagrar rader.
Reservbeteende
Om PHP känner till fälttypen men redigerarskriptet inte registrerar en motsvarande kontroll behåller Blockstudio det sparade värdet och visar ett icke-redigerbart meddelande i redigeraren. Återgivning i frontend får fortfarande det sparade värdet.
Om en fälttyp inte är registrerad i PHP tar Blockstudio inte med den i de genererade attributen WordPress. Registrera definitionen PHP innan blockidentifieringen körs, vanligtvis vid init innan Blockstudio skapar block.