Mukautetut kenttätyypit
Mukautettujen kenttätyyppien avulla teema tai lisäosa voi lisätä uusia Blockstudio-kenttäohjaimia. Ne eroavat mukautetuista kentistä:
custom/{name}viittaa uudelleenkäytettävään ryhmään olemassa olevia kenttiä.namespace/type-namekäyttää rekisteröityä kenttätyyppiä, jolla on oma editorin ohjaimensa ja arvomuotonsa.
Blockstudio sisältää rekisteröintijärjestelmän. Teema tai lisäosa sisältää ohjaimen.
Milloin niitä käytetään
Käytä mukautettua kenttätyyppiä, kun projekti tarvitsee yhteen tarkoitukseen suunnitellun muokkausohjaimen, jonka tulee toimia kaikkialla kuten natiivi Blockstudio-kenttä:
- lohkomääritteet
- uudelleenkäytettävät
custom/{name}-kenttäryhmät - ryhmät, välilehdet ja toistimet
- PHP-, Twig- ja Blade-mallit
- sisältömetatiedot ja asetusten tallennus
- laajennusmallit, kuten
{attributes.margin.top}
Esimerkiksi välistysohjaimella voidaan tallentaa yksi objekti neljän erillisen tekstikentän sijaan:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Nimeäminen
Mukautettujen kenttätyyppien nimien on oltava pieniä kirjaimia, nimiavaruudellisia ja yhdysmerkein erotettuja:
namespace/type-name
Kelvollisia esimerkkejä:
acme/dimensionsacme/text-optionstheme/spacing-token
Varatut nimiavaruudet:
custom/on varattu uudelleenkäytettäville mukautetuille kenttäryhmille.blockstudio/on varattu Blockstudio-ytimelle.
Virheelliset nimet ohitetaan suodattimessa API ja hylätään apufunktiossa API.
PHP-rekisteröinti
Rekisteröi kenttätyypin metatiedot kohteessa 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() palauttaa arvon true, kun rekisteröinti onnistuu, ja arvon false,
kun nimi tai määritys on virheellinen. Voit poistaa manuaalisen
rekisteröinnin käyttämällä funktiota bs_unregister_field_type().
Voit myös käyttää suodatinta API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Määrityksen avaimet
| Avain | Tyyppi | Kuvaus |
|---|---|---|
attribute |
string, array, null |
WordPress-attribuutin tyyppi. Käytä string-, number-, boolean-, object– tai array-tyyppiä tai näiden tyyppien taulukkoa. |
default |
mixed | Rekisterin tason oletusarvo, kun kentälle ei ole määritetty omaa oletusarvoa. |
source |
string | WordPress-attribuutin lähde mukautettuja sarjallistamistapauksia varten. |
produces_attribute |
boolean | Aseta arvoksi false vain näyttäviä ohjaimia varten. Oletusarvo on true. |
editor_script |
string or array | Rekisteröity komentosarjan tunniste tai tunnisteet, jotka lisätään lohkoeditoriin, kun tyyppiä käytetään. |
editor_style |
string or array | Rekisteröity tyylin tunniste tai tunnisteet, jotka lisätään lohkoeditoriin, kun tyyppiä käytetään. |
storage |
array | Tallennusarvon tyyppi sekä REST skeemavihjeet artikkelien metatiedoille ja asetuksille. |
supports |
array | Valinnaiset toimintoliput omaa ohjainta varten. |
translate |
boolean | Aseta arvoksi true, kun arvo on tekstiä, jonka WPML voi kääntää. Edellyttää attribute string. |
Määritys, jonka translate-arvo ei ole totuusarvo tai jossa translate on asetettu arvoon true ja attribute on jokin muu kuin string, on virheellinen. bs_register_field_type() palauttaa arvon false, ja suodatin API ohittaa sen.
WPML
wp bs wpml config ei voi päätellä pelkän rekisteröinnin perusteella, onko mukautetun kenttätyypin arvo tekstiä, joten se jättää tällaiset kentät pois ja tulostaa kustakin varoituksen. Aseta translate arvoon true sellaisen kenttätyypin rekisteröinnissä, joka tallentaa pelkän tekstimerkkijonon, niin komento ilmoittaa sen kentät kuten text-kentät. Kentän voi silti jättää pois asetuksella "translate": false. Katso WPMLsiirrettävien mediatiedostojen viitteet.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript-rekisteröinti
Editorin skripti rekisteröi vastaavan React-ohjaimen:
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() palauttaa arvon true, kun rekisteröinti hyväksytään. Poista
asiakaspuolen rekisteröinti näin:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponentti saa kentän määrityksen ominaisuudet sekä nämä pysyvät ominaisuudet:
| Ominaisuus | Kuvaus |
|---|---|
type |
Kenttätyypin nimi. |
id |
Kentän tunnus. |
field |
Koko kentän määritys lähteestä block.json. |
value |
Nykyinen tallennettu arvo. |
defaultValue |
Kentän oletusarvo. |
onChange |
Tallenna uusi arvo suoraan. |
attributes |
Nykyiset lohkomääritteet. |
block |
Nykyisen lohkotyypin määritys. |
clientId |
Nykyisen editorilohkon asiakastunnus. |
inRepeater |
Onko kenttä toistinrivillä. |
repeaterId |
Nykyinen toistimen polku, jos sellainen on. |
disabled |
Onko kenttä poistettu käytöstä editorissa. |
Mukautettujen kenttätyyppien arvoja ei tallenneta suoraan. Niitä ei käsitellä natiivien select-, radio-, color– tai gradient-asetusten normalisoinnissa.
Arvojen renderöinti
Objektin arvot ovat käytettävissä kuten muutkin Blockstudio-määritteet.
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>
Sisäkkäiset objektipolut toimivat myös laajennusmalleissa:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Tallennus
Kun mukautettua kenttätyyppiä käytetään tallennuksessa postMeta tai option,
Blockstudio käyttää rekisteröityä tallennettavan arvon tyyppiä ja skeemaa REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Määritä rekisteröinnissä kenttätyypille storage.rest_schema, kun kyseessä ovat arvot array ja object. Toistimen alikohteet käyttävät edelleen taulukkopohjaista tallennusta, koska toistin tallentaa rivejä.
Varatoiminta
Jos PHP tuntee kenttätyypin, mutta editorin skripti ei rekisteröi vastaavaa ohjainta, Blockstudio säilyttää tallennetun arvon ja näyttää editorissa huomautuksen, jota ei voi muokata. Käyttöliittymän renderöinti saa edelleen tallennetun arvon.
Jos kenttätyyppiä ei rekisteröidä kohteessa PHP, Blockstudio jättää sen pois luoduista WordPress-määritteistä. Rekisteröi määritys PHP ennen lohkojen tunnistusta, yleensä kohteessa init ennen kuin Blockstudio luo lohkot.