Tipuri de câmpuri personalizate
Tipurile de câmpuri personalizate permit unei teme sau unui plugin să adauge controale noi pentru câmpurile Blockstudio. Acestea diferă de câmpurile personalizate:
custom/{name}face referire la un grup reutilizabil de câmpuri existente.namespace/type-namefolosește un tip de câmp înregistrat, cu propriul control de editor și propria structură a valorii.
Blockstudio furnizează sistemul de înregistrare. Tema sau pluginul dvs. furnizează controlul.
Când să le folosiți
Folosiți un tip de câmp personalizat când un proiect are nevoie de un control de editare cu un scop precis, care să se comporte peste tot ca un câmp Blockstudio nativ:
- atribute de bloc
- grupuri de câmpuri
custom/{name}reutilizabile - grupuri, file și repetitoare
- șabloane PHP, Twig și Blade
- metadate ale articolelor și stocarea opțiunilor
- șabloane de extensie precum
{attributes.margin.top}
De exemplu, un control pentru spațiere poate stoca un singur obiect în locul a patru câmpuri text separate:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Denumire
Numele tipurilor de câmp personalizate trebuie să fie scrise cu litere mici, să aibă spații de nume și să folosească formatul dashcase:
namespace/type-name
Exemple valide:
acme/dimensionsacme/text-optionstheme/spacing-token
Spații de nume rezervate:
custom/este rezervat pentru grupurile reutilizabile de câmpuri personalizate.blockstudio/este rezervat pentru nucleul Blockstudio.
Numele invalide sunt ignorate de filtrul API și respinse de funcția ajutătoare API.
Înregistrare PHP
Înregistrați metadatele tipului de câmp în 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() returnează true dacă înregistrarea reușește și false
dacă numele sau definiția nu sunt valide. Puteți anula o înregistrare manuală
cu bs_unregister_field_type().
Puteți folosi și filtrul API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Cheile definiției
| Cheie | Tip | Descriere |
|---|---|---|
attribute |
string, array, null |
Tipul de atribut WordPress. Folosiți string, number, boolean, object, array sau un tablou cu aceste tipuri. |
default |
mixed | Valoare implicită la nivel de registru atunci când un câmp nu își definește propria valoare implicită. |
source |
string | Sursa atributului WordPress pentru cazuri de serializare personalizate. |
produces_attribute |
boolean | Setați la false pentru controale doar pentru afișare. Valoarea implicită este true. |
editor_script |
string or array | Handle-ul sau handle-urile de script înregistrate care vor fi încărcate în editorul de blocuri când este folosit tipul. |
editor_style |
string or array | Handle-ul sau handle-urile de stil înregistrate care vor fi încărcate în editorul de blocuri când este folosit tipul. |
storage |
array | Indicații privind tipul valorii stocate și schema REST pentru metadatele postărilor și opțiuni. |
supports |
array | Indicatori opționali de capabilități pentru propriul control. |
translate |
boolean | Setați la true când valoarea este text destinat traducerii de către WPML. Necesită attribute string. |
O definiție cu o valoare translate care nu este booleană sau cu translate setat la true și un attribute diferit de string este nevalidă. bs_register_field_type() returnează false, iar filtrul API o ignoră.
WPML
wp bs wpml config nu poate determina doar din înregistrare dacă valoarea unui tip de câmp personalizat este text, așa că omite aceste câmpuri și afișează câte un avertisment pentru fiecare. Setați translate la true în înregistrarea unui tip de câmp care stochează un șir de text simplu, iar comanda declară câmpurile acestuia ca text. Un câmp poate renunța în continuare la acest comportament folosind "translate": false. Consultați WPMLdocumentația.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Înregistrare JavaScript
Scriptul editorului înregistrează controlul React corespunzător:
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() returnează true când înregistrarea este acceptată. Eliminați o înregistrare client cu:
window.blockstudio.unregisterFieldType('acme/dimensions');
Componenta primește proprietățile definiției câmpului, plus aceste proprietăți stabile:
| Proprietate | Descriere |
|---|---|
type |
Numele tipului de câmp. |
id |
ID-ul câmpului. |
field |
Definiția completă a câmpului din block.json. |
value |
Valoarea salvată curentă. |
defaultValue |
Valoarea implicită a câmpului. |
onChange |
Stochează direct o valoare nouă. |
attributes |
Atributele blocului curent. |
block |
Definiția tipului blocului curent. |
clientId |
ID-ul client al blocului curent din editor. |
inRepeater |
Dacă câmpul se află într-un rând al repetitorului. |
repeaterId |
Calea repetitorului curent, dacă există. |
disabled |
Dacă acest câmp este dezactivat în editor. |
Valorile tipurilor de câmpuri personalizate sunt stocate direct. Ele nu trec prin normalizarea opțiunilor native select, radio, color sau gradient.
Redarea valorilor
Valorile obiectelor sunt disponibile ca orice alt atribut Blockstudio.
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>
Căile imbricate ale obiectelor funcționează și în șabloanele de extensie:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Stocare
Când se folosește un tip de câmp personalizat cu stocarea postMeta sau option,
Blockstudio folosește tipul valorii stocate înregistrate și schema REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Pentru valorile array și object, definiți storage.rest_schema în înregistrarea tipului de câmp. Descendenții repetitoarelor continuă să folosească stocarea bazată pe tablouri, deoarece un repetitor stochează rânduri.
Comportamentul de rezervă
Dacă PHP cunoaște tipul de câmp, dar scriptul editorului nu înregistrează un control corespunzător, Blockstudio păstrează valoarea salvată și afișează o notificare needitabilă în editor. Redarea în partea publică primește în continuare valoarea salvată.
Dacă un tip de câmp nu este înregistrat în PHP, Blockstudio îl omite din atributele WordPress generate. Înregistrați definiția PHP înainte de rularea descoperirii blocurilor, de obicei în init înainte ca Blockstudio să construiască blocurile.