Egyéni mezőtípusok
Az egyéni mezőtípusok lehetővé teszik, hogy egy téma vagy bővítmény új Blockstudio mezővezérlőket adjon hozzá. Ezek különböznek az egyéni mezőktől:
- A
custom/{name}meglévő mezők újrafelhasználható csoportjára hivatkozik. - A
namespace/type-namesaját szerkesztővezérlővel és értékszerkezettel rendelkező regisztrált mezőtípust használ.
A Blockstudio biztosítja a regisztrációs rendszert. A vezérlőt a téma vagy bővítmény biztosítja.
Mikor használja őket
Akkor használjon egyéni mezőtípust, ha a projektnek olyan egyetlen célra szolgáló szerkesztővezérlőre van szüksége, amely mindenhol natív Blockstudio mezőként működik:
- blokkattribútumok
- újrafelhasználható
custom/{name}mezőcsoportok - csoportok, fülek és ismétlők
- PHP, Twig és Blade sablonok
- bejegyzésmetaadatok és beállítások tárolása
- bővítménysablonok, például
{attributes.margin.top}
Például egy térközvezérlő négy külön szövegmező helyett egyetlen objektumot tárolhat:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Elnevezés
Az egyéni mezőtípusok neveinek kisbetűsnek, névtérrel ellátottnak és kötőjeles formátumúnak kell lenniük:
namespace/type-name
Érvényes példák:
acme/dimensionsacme/text-optionstheme/spacing-token
Fenntartott névterek:
- A
custom/az újrafelhasználható egyéni mezőcsoportok számára van fenntartva. - A
blockstudio/a Blockstudio alapcsomag számára van fenntartva.
Az érvénytelen neveket a API szűrő figyelmen kívül hagyja, a API segédfüggvény pedig elutasítja.
PHP regisztráció
Regisztrálja a mezőtípus metaadatait a PHP fájlban:
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'],
],
],
]);
});
A bs_register_field_type() sikeres regisztráció esetén true értéket ad vissza, érvénytelen név vagy definíció esetén pedig false értéket.
A kézi regisztrációt a bs_unregister_field_type() segítségével vonhatja vissza.
Használhatja a API szűrőt is:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Definíciós kulcsok
| Kulcs | Típus | Leírás |
|---|---|---|
attribute |
string, array, null |
WordPress attribútumtípus. Használja a string, number, boolean, object, array értékek egyikét vagy ezek tömbjét. |
default |
vegyes | Regiszterszintű alapértelmezett érték, ha egy mező nem határoz meg saját alapértelmezett értéket. |
source |
karakterlánc | WordPress attribútumforrás egyéni szerializálási esetekhez. |
produces_attribute |
logikai | Állítsa false értékre a csak megjelenítésre szolgáló vezérlőknél. Alapértelmezett értéke true. |
editor_script |
karakterlánc vagy tömb | A blokk szerkesztőben használt típushoz betöltendő regisztrált parancsfájl-azonosító vagy -azonosítók. |
editor_style |
karakterlánc vagy tömb | A blokk szerkesztőben használt típushoz betöltendő regisztrált stílusazonosító vagy -azonosítók. |
storage |
tömb | A tárolási érték típusa és REST sématippjei a bejegyzésmetához és a beállításokhoz. |
supports |
tömb | Opcionális képességjelzők a saját vezérlőhöz. |
translate |
logikai | Állítsa true értékre, ha az érték a WPML által fordítandó szöveg. Ehhez szükséges: attribute string. |
Érvénytelen az a definíció, amelynek translate értéke nem logikai, vagy amelyben a translate értéke true, az attribute pedig nem string.
A bs_register_field_type() false értéket ad vissza, a API szűrő pedig figyelmen kívül hagyja.
WPML
wp bs wpml config a regisztráció alapján nem tudja megállapítani, hogy az egyéni mezőtípus értéke szöveg-e, ezért kihagyja az ilyen mezőket, és mindegyikhez figyelmeztetést jelenít meg. Állítsa a translate értékét true-re a sima szöveges karakterláncot tároló mezőtípus regisztrációjában, és a parancs az ilyen mezőket text mezőkként deklarálja. A mezők a "translate": false használatával továbbra is kihagyhatók. Lásd: WPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript regisztráció
A szerkesztőszkript regisztrálja a hozzá tartozó React vezérlőt:
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,
});
},
}),
),
);
},
});
A registerFieldType() akkor adja vissza a true értéket, ha a regisztrációt elfogadja. Az ügyféloldali regisztráció eltávolítása:
window.blockstudio.unregisterFieldType('acme/dimensions');
A komponens megkapja a meződefiníció tulajdonságait, valamint ezeket az állandó tulajdonságokat:
| Tulajdonság | Leírás |
|---|---|
type |
Mezőtípus neve. |
id |
Mezőazonosító. |
field |
A teljes meződefiníció innen: block.json. |
value |
Jelenleg mentett érték. |
defaultValue |
A mező alapértelmezett értéke. |
onChange |
Új érték közvetlen mentése. |
attributes |
Aktuális blokkattribútumok. |
block |
Aktuális blokk típusának definíciója. |
clientId |
Aktuális szerkesztőblokk ügyfélazonosítója. |
inRepeater |
A mező ismétlősorban van-e. |
repeaterId |
Aktuális ismétlőútvonal, ha van. |
disabled |
A mező le van-e tiltva a szerkesztőben. |
Az egyéni mezőtípusok értékei közvetlenül tárolódnak. Nem esnek át a natív select, radio, color vagy gradient beállításnormalizáláson.
Értékek megjelenítése
Az objektumértékek ugyanúgy elérhetők, mint bármely más Blockstudio attribútum.
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>
A beágyazott objektumútvonalak is működnek a bővítménysablonokban:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Tárolás
Ha egyéni mezőtípust használ a postMeta vagy a option tárolással, a Blockstudio a regisztrált tárolási értéktípust és a REST sémát használja.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
A array és object értékeknél határozza meg a storage.rest_schema értéket a mezőtípus regisztrációjában. Az ismétlők leszármazottai továbbra is tömbalapú tárolást használnak, mivel az ismétlő sorokat tárol.
Visszaesési viselkedés
Ha a PHP ismeri a mezőtípust, de a szerkesztőszkript nem regisztrál hozzá illő vezérlőt, a Blockstudio megőrzi a mentett értéket, és nem szerkeszthető értesítést jelenít meg a szerkesztőben. A frontend megjelenítése továbbra is megkapja a mentett értéket.
Ha a mezőtípus nincs regisztrálva a PHP rendszerben, a Blockstudio kihagyja a létrehozott WordPress attribútumokból. Regisztrálja a PHP definíciót a blokkok felderítése előtt, általában a init ponton, mielőtt a Blockstudio létrehozza a blokkokat.