Vlastní typy polí
Vlastní typy polí umožňují šabloně nebo pluginu přidat nové ovládací prvky polí Blockstudio. Liší se od vlastních polí:
custom/{name}odkazuje na opakovaně použitelnou skupinu existujících polí.namespace/type-namepoužívá registrovaný typ pole s vlastním ovládacím prvkem editoru a tvarem hodnoty.
Blockstudio poskytuje registrační systém. Ovládací prvek dodává vaše šablona nebo plugin.
Kdy je použít
Vlastní typ pole použijte, když projekt potřebuje jednoúčelový ovládací prvek pro úpravy, který se má všude chovat jako nativní pole Blockstudio:
- atributy bloků
- opakovaně použitelné skupiny polí
custom/{name} - skupiny, karty a opakovače
- šablony PHP, Twig a Blade
- metadata příspěvků a ukládání nastavení
- rozšiřující šablony, jako je
{attributes.margin.top}
Například ovládací prvek pro rozestupy může ukládat jeden objekt místo čtyř 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"
}
}
]
}
}
Pojmenování
Názvy vlastních typů polí musí být psány malými písmeny, musí být opatřené jmenným prostorem a používat pomlčky:
namespace/type-name
Platné příklady:
acme/dimensionsacme/text-optionstheme/spacing-token
Rezervované jmenné prostory:
custom/je vyhrazeno pro opakovaně použitelné skupiny vlastních polí.blockstudio/je vyhrazeno pro jádro Blockstudio.
Neplatné názvy filtr API ignoruje a pomocná funkce API odmítne.
Registrace PHP
Zaregistrujte metadata typu pole 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() vrací true, pokud registrace uspěje, a false, pokud je název nebo definice neplatná. Ruční registraci můžete zrušit pomocí bs_unregister_field_type().
Můžete také použít filtr API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Klíče definice
| Klíč | Typ | Popis |
|---|---|---|
attribute |
string, array, null |
Typ atributu WordPress. Použijte string, number, boolean, object, array nebo pole těchto typů. |
default |
mixed | Výchozí hodnota na úrovni registru, pokud pole nemá definovanou vlastní výchozí hodnotu. |
source |
string | Zdroj atributu WordPress pro vlastní případy serializace. |
produces_attribute |
boolean | Pro ovládací prvky určené pouze k zobrazení nastavte na false. Výchozí hodnota je true. |
editor_script |
string or array | Registrovaný skript nebo skripty, které se mají zařadit do editoru bloků, když se tento typ použije. |
editor_style |
string or array | Registrovaný styl nebo styly, které se mají zařadit do editoru bloků, když se tento typ použije. |
storage |
array | Typ ukládané hodnoty a náznaky schématu REST pro metadata příspěvků a možnosti. |
supports |
array | Volitelné příznaky schopností pro vlastní ovládací prvek. |
translate |
boolean | Nastavte na true, pokud je hodnota text určený k překladu pomocí WPML. Vyžaduje attribute string. |
Definice s hodnotou translate, která není typu boolean, nebo s translate nastaveným na true a hodnotou attribute jinou než string, je neplatná.
bs_register_field_type() vrací false a filtr API ji ignoruje.
WPML
wp bs wpml config nedokáže pouze z registrace určit, zda je hodnota vlastního typu pole text, proto taková pole vynechá a u každého vypíše upozornění. V registraci typu pole, který ukládá prostý textový řetězec, nastavte translate na true; příkaz pak jeho pole deklaruje jako pole typu text. Pole se může z této možnosti stále vyřadit pomocí "translate": false. Viz WPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registrace JavaScript
Skript editoru registruje odpovídající ovládací prvek 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() vrací true, pokud je registrace přijata. Registraci na straně klienta odeberte takto:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponenta dostává vlastnosti definice pole a také tyto stabilní vlastnosti:
| Vlastnost | Popis |
|---|---|
type |
Název typu pole. |
id |
ID pole. |
field |
Úplná definice pole z block.json. |
value |
Aktuální uložená hodnota. |
defaultValue |
Výchozí hodnota pole. |
onChange |
Uloží novou hodnotu přímo. |
attributes |
Aktuální atributy bloku. |
block |
Aktuální definice typu bloku. |
clientId |
ID bloku klienta v aktuálním editoru. |
inRepeater |
Zda je pole uvnitř řádku opakovače. |
repeaterId |
Aktuální cesta opakovače, pokud existuje. |
disabled |
Zda je pole v editoru zakázáno. |
Hodnoty vlastních typů polí se ukládají přímo. Neprocházejí normalizací možností nativních select, radio, color ani gradient.
Vykreslování hodnot
Hodnoty objektů jsou dostupné stejně jako jakýkoli jiný 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>
V šablonách rozšíření fungují také vnořené cesty k objektům:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Ukládání
Když se vlastní typ pole používá s úložištěm postMeta nebo option,
Blockstudio využívá registrovaný typ ukládané hodnoty a schéma REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
U hodnot array a object definujte storage.rest_schema při registraci typu pole. Potomci opakovače nadále používají úložiště založené na polích, protože opakovač ukládá řádky.
Záložní chování
Pokud PHP zná typ pole, ale skript editoru nezaregistruje odpovídající ovládací prvek, Blockstudio zachová uloženou hodnotu a v editoru zobrazí upozornění, které nelze upravit. Frontendové vykreslování stále dostane uloženou hodnotu.
Pokud typ pole není zaregistrován v PHP, Blockstudio jej vynechá z vygenerovaných atributů WordPress. Zaregistrujte definici PHP ještě před spuštěním zjišťování bloků, obvykle v init předtím, než Blockstudio sestaví bloky.