Vlastné typy polí
Typy vlastných polí umožňujú téme alebo pluginu pridať nové Blockstudio ovládacie prvky polí. Líšia sa od vlastných polí:
custom/{name}odkazuje na opätovne použiteľnú skupinu existujúcich polí.namespace/type-namepoužíva zaregistrovaný typ poľa s vlastným ovládacím prvkom editora a štruktúrou hodnoty.
Blockstudio poskytuje registračný systém. Ovládací prvok dodáva vaša téma alebo plugin.
Kedy ich použiť
Vlastný typ poľa použite, keď projekt potrebuje jednoúčelový ovládací prvok úprav, ktorý sa má všade správať ako natívne pole Blockstudio:
- atribúty bloku
- opätovne použiteľné skupiny polí
custom/{name} - skupiny, karty a opakovače
- šablóny PHP, Twig a Blade
- metaúdaje príspevku a ukladanie nastavení
- rozširujúce šablóny, napríklad
{attributes.margin.top}
Napríklad ovládací prvok rozostupov môže ukladať jeden objekt namiesto štyroch samostatných textových polí:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Pomenovanie
Názvy vlastných typov polí musia byť napísané malými písmenami, mať menný priestor a používať pomlčky:
namespace/type-name
Platné príklady:
acme/dimensionsacme/text-optionstheme/spacing-token
Rezervované menné priestory:
custom/je rezervovaný pre opätovne použiteľné skupiny vlastných polí.blockstudio/je rezervovaný pre jadro Blockstudio.
Neplatné názvy filter API ignoruje a pomocná funkcia API odmietne.
Registrácia PHP
Zaregistrujte metadáta typu poľa v 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() vracia true, keď sa registrácia podarí, a false, keď je názov alebo definícia neplatná. Ručnú registráciu môžete zrušiť pomocou bs_unregister_field_type().
Môžete tiež použiť filter API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Kľúče definície
| Kľúč | Typ | Popis |
|---|---|---|
attribute |
string, array, null |
Typ atribútu WordPress. Použite string, number, boolean, object, array alebo pole týchto typov. |
default |
mixed | Predvolená hodnota na úrovni registra, ak pole nemá vlastnú predvolenú hodnotu. |
source |
string | Zdroj atribútu WordPress pre vlastné prípady serializácie. |
produces_attribute |
boolean | Pri ovládacích prvkoch určených iba na zobrazenie nastavte na false. Predvolená hodnota je true. |
editor_script |
string or array | Registrovaný identifikátor skriptu alebo identifikátory, ktoré sa majú zaradiť do frontu v editore blokov pri použití daného typu. |
editor_style |
string or array | Registrovaný identifikátor štýlu alebo identifikátory, ktoré sa majú zaradiť do frontu v editore blokov pri použití daného typu. |
storage |
array | Typ ukladanej hodnoty a náznaky schémy REST pre metaúdaje príspevkov a možnosti. |
supports |
array | Voliteľné príznaky schopností pre vlastný ovládací prvok. |
translate |
boolean | Ak je hodnota textom určeným na preklad pomocou WPML, nastavte na true. Vyžaduje attribute string. |
Definícia s hodnotou translate, ktorá nie je booleovská, alebo s
translate nastaveným na true a hodnotou attribute odlišnou od string, je neplatná.
bs_register_field_type() vráti false a filter API ju ignoruje.
WPML
wp bs wpml config nedokáže z registrácie samotnej určiť, či je hodnota
vlastného typu poľa textom, preto takéto polia vynechá a pri každom vypíše
upozornenie. Pri registrácii typu poľa, ktorý ukladá obyčajný textový reťazec,
nastavte translate na true a príkaz bude jeho polia deklarovať ako polia
text. Pole možno stále vynechať pomocou "translate": false. Pozrite si
WPMLdokumentáciu.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registrácia JavaScript
Skript editora zaregistruje zodpovedajúci ovládací prvok React:
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() vráti true, keď je registrácia prijatá. Registráciu na strane klienta odstráňte takto:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponent dostane vlastnosti definície poľa a tieto stabilné vlastnosti:
| Vlastnosť | Opis |
|---|---|
type |
Názov typu poľa. |
id |
ID poľa. |
field |
Úplná definícia poľa z block.json. |
value |
Aktuálna uložená hodnota. |
defaultValue |
Predvolená hodnota poľa. |
onChange |
Uloží novú hodnotu priamo. |
attributes |
Aktuálne atribúty bloku. |
block |
Aktuálna definícia typu bloku. |
clientId |
Aktuálne ID bloku na strane klienta v editore. |
inRepeater |
Informácia, či je pole v riadku opakovača. |
repeaterId |
Aktuálna cesta k opakovaču, ak existuje. |
disabled |
Informácia, či je pole v editore zakázané. |
Hodnoty typov vlastných polí sa ukladajú priamo. Neprechádzajú normalizáciou natívnych možností select, radio, color ani gradient.
Vykresľovanie hodnôt
Hodnoty objektov sú dostupné rovnako ako akýkoľvek iný atribút 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>
V šablónach rozšírení fungujú aj vnorené cesty k objektom:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Ukladanie
Keď sa vlastný typ poľa používa s úložiskom postMeta alebo option,
Blockstudio používa zaregistrovaný typ ukladanej hodnoty a schému REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Pre hodnoty array a object definujte storage.rest_schema v registrácii typu poľa. Potomkovia opakovača naďalej používajú úložisko založené na poliach, pretože opakovač ukladá riadky.
Záložné správanie
Ak PHP pozná typ poľa, ale skript editora nezaregistruje zodpovedajúci ovládací prvok, Blockstudio zachová uloženú hodnotu a zobrazí v editore upozornenie, ktoré nemožno upravovať. Vykresľovanie na frontende naďalej dostáva uloženú hodnotu.
Ak typ poľa nie je zaregistrovaný v PHP, Blockstudio ho vynechá z vygenerovaných atribútov WordPress. Definíciu PHP zaregistrujte ešte pred spustením zisťovania blokov, zvyčajne v init predtým, ako Blockstudio vytvorí bloky.