Kohandatud väljatüübid
Kohandatud väljatüübid võimaldavad teemal või pluginatil lisada uusi Blockstudio-väljade juhtelemente. Need erinevad kohandatud väljadest:
custom/{name}viitab korduvkasutatavale rühmale, mis koosneb olemasolevatest väljadest.namespace/type-namekasutab registreeritud väljatüüpi, millel on oma redaktori juhtelement ja väärtuse kuju.
Blockstudio sisaldab registreerimissüsteemi. Teema või plugin sisaldab juhtelementi.
Millal neid kasutada
Kasutage kohandatud väljatüüpi, kui projekt vajab kindla otstarbega redigeerimisjuhtelementi, mis peaks kõikjal toimima nagu Blockstudio algne väli:
- ploki atribuudid
- korduvkasutatavad
custom/{name}-väljarühmad - rühmad, vahekaardid ja kordajad
- PHP, Twig ja Blade mallid
- postituse metaandmed ja suvandite salvestus
- laiendusmallid, näiteks
{attributes.margin.top}
Näiteks saab vahe juhtelement salvestada ühe objekti nelja eraldi tekstivälja asemel:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Nime andmine
Kohandatud väljatüüpide nimed peavad olema väiketähtedega, nimeruumiga ja sidekriipsudega eraldatud:
namespace/type-name
Kehtivad näited:
acme/dimensionsacme/text-optionstheme/spacing-token
Reserveeritud nimeruumid:
custom/on reserveeritud korduvkasutatavate kohandatud väljarühmade jaoks.blockstudio/on reserveeritud Blockstudio tuuma jaoks.
Filtri API abil eiratakse kehtetuid nimesid ja abifunktsioon API lükkab need tagasi.
PHP registreerimine
Registreerige väljatüübi metaandmed asukohas 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() tagastab registreerimise õnnestumisel väärtuse true ja juhul, kui nimi või definitsioon on vigane, väärtuse false.
Käsitsi registreeringu saab eemaldada funktsiooniga bs_unregister_field_type().
Võite kasutada ka filtrit API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Definitsiooni võtmed
| Võti | Tüüp | Kirjeldus |
|---|---|---|
attribute |
string, array, null |
WordPress atribuudi tüüp. Kasutage string, number, boolean, object, array või nende tüüpide massiivi. |
default |
mixed | Registritaseme vaikeväärtus, kui väli ei määra oma vaikeväärtust. |
source |
string | WordPress atribuudi allikas kohandatud serialiseerimisjuhtude jaoks. |
produces_attribute |
boolean | Ainult kuvamiseks mõeldud juhtelementide korral määrake väärtuseks false. Vaikimisi on true. |
editor_script |
string or array | Registreeritud skripti käepide või käepidemed, mis lisatakse plokiredaktori järjekorda tüübi kasutamisel. |
editor_style |
string or array | Registreeritud stiili käepide või käepidemed, mis lisatakse plokiredaktori järjekorda tüübi kasutamisel. |
storage |
array | Salvestusväärtuse tüüp ja REST skeemivihjed post meta ja valikute jaoks. |
supports |
array | Valikulised võimekuse lipud oma juhtelemendi jaoks. |
translate |
boolean | Määrake väärtuseks true, kui väärtus on tekst, mida WPML peaks tõlkima. Vajab attribute string. |
Määratlus, mille translate väärtus ei ole tõeväärtus või mille puhul
translate väärtuseks on määratud true ja attribute erineb väärtusest string, on vigane.
bs_register_field_type() tagastab false ja filter API eirab seda.
WPML
wp bs wpml config ei saa registreeringu põhjal üksi kindlaks teha, kas kohandatud väljatüübi väärtus
on tekst, seega jätab see sellised väljad välja ja kuvab igaühe kohta hoiatuse. Määrake translate väärtuseks true sellise väljatüübi registreeringus, mis salvestab lihtteksti stringi; seejärel käsitleb käsk selle välju nagu text välju. Välja saab endiselt välistada väärtusega "translate": false. Lisateavet leiate jaotisest WPMLkaasaskantavad meediaviited.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript registreerimine
Redaktori skript registreerib vastava React juhtelemendi:
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() tagastab registreerimise kinnitamisel väärtuse true. Kliendipoolse registreeringu eemaldamiseks kasutage:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponent saab väljadefinitsiooni atribuudid ning järgmised püsivad rekvisiidid:
| Rekvisiit | Kirjeldus |
|---|---|
type |
Väljatüübi nimi. |
id |
Välja ID. |
field |
Täielik väljadefinitsioon asukohast block.json. |
value |
Praegu salvestatud väärtus. |
defaultValue |
Välja vaikeväärtus. |
onChange |
Uue väärtuse otse salvestamine. |
attributes |
Praeguse ploki atribuudid. |
block |
Praeguse ploki tüübi definitsioon. |
clientId |
Praeguse redaktori ploki kliendi ID. |
inRepeater |
Kas väli asub kordaja reas. |
repeaterId |
Praegune kordaja tee, kui see on olemas. |
disabled |
Kas väli on redaktoris keelatud. |
Kohandatud väljatüübi väärtused salvestatakse otse. Neid ei teisendata algse select, radio, color ega gradient suvandite normaliseerimise kaudu.
Väärtuste renderdamine
Objektväärtused on saadaval nagu kõik muud Blockstudio-atribuudid.
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>
Pesastatud objektide teed toimivad ka laiendusmallides:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Salvestus
Kui kohandatud väljatüüpi kasutatakse salvestusega postMeta või option, kasutab Blockstudio registreeritud salvestusväärtuse tüüpi ja REST skeemi.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Väärtuste array ja object puhul määrake registreerimisel väljatüübil storage.rest_schema. Kordaja järglased kasutavad edasi massiivi põhist salvestust, sest kordaja salvestab ridu.
Varukäitumine
Kui PHP tunneb väljatüüpi, kuid redaktori skript ei registreeri sellele vastavat juhtelementi, säilitab Blockstudio salvestatud väärtuse ja kuvab redaktoris mitteredigeeritava teate. Eesosa renderdus saab salvestatud väärtuse endiselt kätte.
Kui väljatüüpi pole asukohas PHP registreeritud, jätab Blockstudio selle genereeritud WordPress atribuutidest välja. Registreerige PHP definitsioon enne ploki tuvastamise käivitumist, tavaliselt kohas init enne, kui Blockstudio plokid koostab.