Tinkinti laukų tipai
Tinkintų laukų tipai leidžia temai arba papildiniui pridėti naujus Blockstudio laukų valdiklius. Jie skiriasi nuo tinkintų laukų:
custom/{name}nurodo pakartotinai naudojamą esamų laukų grupę.namespace/type-namenaudoja registruotą lauko tipą su atskiru redaktoriaus valdikliu ir reikšmės struktūra.
Blockstudio pateikia registravimo sistemą. Jūsų tema arba papildinys pateikia valdiklį.
Kada juos naudoti
Naudokite tinkintą lauko tipą, kai projektui reikia vienos paskirties redagavimo valdiklio, kuris visur veiktų kaip įtaisytasis Blockstudio laukas:
- bloko atributai
- pakartotinai naudojamos
custom/{name}laukų grupės - grupės, kortelės ir kartotuvai
- PHP, Twig ir Blade šablonai
- įrašo metaduomenys ir parinkčių saugykla
- plėtinių šablonai, pvz.,
{attributes.margin.top}
Pavyzdžiui, tarpų valdiklis gali saugoti vieną objektą, o ne keturis atskirus teksto laukus:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Pavadinimai
Tinkintų laukų tipų pavadinimai turi būti mažosiomis raidėmis, su vardų sritimi ir brūkšneliais:
namespace/type-name
Tinkami pavyzdžiai:
acme/dimensionsacme/text-optionstheme/spacing-token
Rezervuotos vardų sritys:
custom/rezervuota pakartotinai naudojamoms tinkintų laukų grupėms.blockstudio/rezervuota Blockstudio branduoliui.
Netinkamus pavadinimus filtras API ignoruoja, o pagalbinė funkcija API atmeta.
PHP registravimas
Užregistruokite lauko tipo metaduomenis faile 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() grąžina true, jei registracija pavyksta, ir false, jei pavadinimas arba aprašas netinkamas. Rankinę registraciją galite atšaukti naudodami bs_unregister_field_type().
Taip pat galite naudoti filtrą API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Aprašo raktai
| Raktas | Tipas | Aprašymas |
|---|---|---|
attribute |
string, array, null |
WordPress atributo tipas. Naudokite string, number, boolean, object, array arba šių tipų masyvą. |
default |
mixed | Registro lygmens numatytoji reikšmė, kai laukas neturi savo numatytosios reikšmės. |
source |
string | WordPress atributo šaltinis tinkintiems serializavimo atvejams. |
produces_attribute |
boolean | Tik rodymo valdikliams nustatykite false. Numatytoji reikšmė yra true. |
editor_script |
string or array | Užregistruota scenarijaus programa arba programos, kurias reikia įtraukti į bloko redaktorių, kai naudojamas šis tipas. |
editor_style |
string or array | Užregistruotas stiliaus išteklius arba ištekliai, kuriuos reikia įtraukti į bloko redaktorių, kai naudojamas šis tipas. |
storage |
array | Saugyklos reikšmės tipo ir REST schemos užuominos įrašo metaduomenims ir parinktims. |
supports |
array | Pasirenkamos jūsų valdiklio galimybių vėliavėlės. |
translate |
boolean | Nustatykite true, kai reikšmė yra tekstas, kurį turi išversti WPML. Reikia attribute string. |
Apibrėžtis, kurios translate reikšmė nėra loginė, arba kurioje translate nustatytas į true, o attribute nėra string, yra netinkama. bs_register_field_type() grąžina false, o filtras API jos nepaiso.
WPML
wp bs wpml config vien iš registracijos negali nustatyti, ar pasirinktinio lauko tipo reikšmė yra tekstas, todėl tokius laukus praleidžia ir pateikia įspėjimą apie kiekvieną iš jų. Užregistruodami lauko tipą, kuriame saugoma paprasto teksto eilutė, nustatykite translate į true; tuomet komanda deklaruoja jo laukus kaip text laukus. Laukui vis tiek galima išjungti šią parinktį naudojant "translate": false. Žr. WPMLtekstinių laukų dokumentaciją.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript registravimas
Redaktoriaus scenarijus užregistruoja atitinkamą React valdiklį:
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() grąžina true, jei registracija priimama. Kliento registraciją pašalinkite taip:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponentas gauna lauko aprašo savybes ir šias nekintančias ypatybes:
| Ypatybė | Aprašymas |
|---|---|
type |
Lauko tipo pavadinimas. |
id |
Lauko ID. |
field |
Visas lauko aprašas iš block.json. |
value |
Dabartinė išsaugota reikšmė. |
defaultValue |
Numatytoji lauko reikšmė. |
onChange |
Tiesiogiai išsaugoti naują reikšmę. |
attributes |
Dabartiniai bloko atributai. |
block |
Dabartinio bloko tipo aprašas. |
clientId |
Dabartinio redaktoriaus bloko kliento ID. |
inRepeater |
Ar laukas yra kartotuvo eilutėje. |
repeaterId |
Dabartinis kartotuvo kelias, jei toks yra. |
disabled |
Ar laukas redaktoriuje išjungtas. |
Tinkintų laukų tipų reikšmės saugomos tiesiogiai. Jos neapdorojamos naudojant įprastą select, radio, color ar gradient parinkčių normalizavimą.
Reikšmių atvaizdavimas
Objektų reikšmės pasiekiamos kaip ir bet kuris kitas Blockstudio atributas.
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>
Įdėtuosiuose šablonuose taip pat veikia įdėtų objektų keliai:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Saugykla
Kai tinkintas lauko tipas naudojamas su postMeta arba option saugykla,
Blockstudio naudoja registruotą saugyklos reikšmės tipą ir REST schemą.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
array ir object reikšmėms lauko tipo registracijoje apibrėžkite storage.rest_schema. Kartotuvo žemesni elementai toliau naudoja masyvais pagrįstą saugyklą, nes kartotuvas saugo eilutes.
Atsarginė elgsena
Jei PHP žino lauko tipą, bet redaktoriaus scenarijus neužregistruoja atitinkamo valdiklio, Blockstudio išsaugo įrašytą reikšmę ir redaktoriuje rodo pranešimą, kurio negalima redaguoti. Svetainės atvaizdavimas vis tiek gauna išsaugotą reikšmę.
Jei lauko tipas neužregistruotas PHP, Blockstudio neįtraukia jo į sugeneruotus WordPress atributus. Užregistruokite PHP aprašą prieš vykdant blokų aptikimą, paprastai faile init, kad Blockstudio galėtų sukurti blokus.