Laiendused
Laiendused võimaldavad lihtsa .json-põhise API abil laiendada mis tahes registreeritud plokki oma WordPress paigalduses; see sarnaneb block.json konfiguratsiooniga. See hõlmab põhikomplekti plokke, kolmandate osapoolte plokke ja Blockstudio abil loodud plokke.
Kõiki väljatüüpe saab lisada mis tahes plokile ning andmed salvestatakse ploki atribuutidesse. Laienduste puhul on saadaval kõik atribuutide funktsioonid, näiteks filtreerimine, keelamine, tingimusloogika ja valikute täitmine.
Laienduste tüübid
Laiendatud väärtusi saab kasutada mitmel moel:
- class: Lisa plokile atribuudi väärtuse abil klass
- style: Lisa plokile atribuudi väärtuse abil tekstisisesed stiilid
- attributes: Määra plokile otse mis tahes atribuudi väärtus
- data attributes: Määra laienduse väärtuste abil konkreetsed andmeatribuudid
Seadistamine
Kujutage ette järgmist olukorda: soovite lisada kohandatud klassi select välja igale tuumplokile. Selleks tuleb vaid lisada see .json fail ükskõik kuhu oma plokikaustas ning see registreeritakse automaatselt laiendusena.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
See lisab igale tuumplokile välja customColor, mille abil saate määrata ploki teksti värvi.
Faili nimi
Kuna renderdusmalli pole, ei vaja laiendus vastavat index faili ega pea seega kandma nime block.json. Nii saab kõiki laiendusi mugavalt ühes kaustas hoida. Sama plokki võivad laiendada mitu faili, näiteks kaks faili väärtusega "name": "core/*"; kumbki registreerib oma väljad.
Skeem
Blockstudio pakub laienduse konfiguratsioonide jaoks kohandatud JSON skeemi:
Nimi
Konfiguratsiooniobjekti atribuut name määrab, milliseid plokke laiendatakse. Vastavalt vajadusele saab valida kolme võimaluse vahel:
- blockName: ühe ploki nimi, e.g.
core/paragraph - [blockNameA, blockNameB]: plokinimede massiiv, e.g.
["core/paragraph", "core/heading"] - core/*: metamärk kindlat tüüpi kõigi plokkide laiendamiseks
Iga tärniga lõppev nimi on eesliite metamärk, mitte ainult core/*. Järgmine laiendus rakendub igale plokile, mille nimi algab my-plugin/, sealhulgas plokkidele, mis on loodud Blockstudio abil:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Plokkide välistamine
Kasutage ülataseme exclude massiivi, et jätta vahele plokid, mis muidu vastaksid tingimusele name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Välistamisel kasutatakse sama täpse nime ja lõpus oleva * järgi eesliite sobitamise loogikat nagu name puhul.
Need on üksiknimede, nimeloendite ja metamärkide ees ülimuslikud. Välistatud plokk ei saa laienduse redaktorivälju ega oma kasutajaliidese atribuute või varasid. Muud sobivad laiendused töötavad endiselt. Olemasoleva käitumise säilitamiseks jätke exclude määramata või kasutage tühja massiivi.
Blockstudio võti
Nii nagu kohandatud plokkide puhul block.json kasutamisel, peab ka siin konfiguratsiooniobjektis olema atribuut blockstudio, mille väärtuseks on true (extend).
Asukoht
Vaikimisi kuvatakse laiendused plokiinspektoris omaette vahekaardil. Kui soovite laiendused mujale tõsta, kasutage atribuuti group:
- settings: vaikeasukoht
- styles: stiilide vahekaart
- advanced: täpsemate seadete vahekaart
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Prioriteet
Atribuudi priority abil saate määrata laienduste kuvamise järjekorra. Suurema prioriteediga laiendused kuvatakse hiljem. Määrake see faili ülaosas nagu seadistuse näites või jaotises extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Kui mõlemad on määratud, eelistatakse väärtust blockstudio.extend.priority.
Atribuudid
Lisateavet atribuutide toimimise kohta leiate atribuutide jaotisest.
Laiendustes kasutatavate atribuutide puhul on oluline vaid atribuut set. Seda kasutatakse atribuudi väärtuse rakendamiseks ühele laienduse tüübile.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Väärtuste hankimine
Atribuudi väärtuse saamiseks kasutatakse looksulgude sees punktiga eraldatud kirjapilti.
Pesastatud väärtusi saab hankida ka siis, kui atribuut tagastab ühe väärtuse asemel mitu väärtust, näiteks valikuid sisaldavate väljatüüpide tagastusvorminguks both määramisel.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
Ülaltoodud näites määratakse atribuudile style väärtus color: #f00 või color: #00f ning atribuudile data-color väärtus Red või Blue, olenevalt väärtusest.
Praegu saab määratluses set kasutada ainult aktiivse atribuudi väärtusi. Teiste atribuutide väärtuste kasutamise võimalus võidakse lisada tulevikus.
Massiivid
Massiivide kasutamisel rakendatakse atribuuti set massiivi igale elemendile.
Iga üksus lisab oma klassi või stiilideklaratsiooni. Kõik muud atribuudid sisaldavad üht väärtust, seega kirjutab iga üksus selle üle ja kehtima jääb viimase väärtus. Määrake join väärtuseks true, et kirjutada selle asemel kõigi üksuste tulemused, eraldatuna tühikutega ning ilma tühjade või korduvate väärtusteta; nii vastab valitud üksustele näiteks valija [data-langs~="en"]. join ei mõjuta class ega style, samuti mitte välju, mis tagastavad ühe väärtuse.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Mõlema valiku tegemisel renderdatakse data-langs="en de". Ilma valikuta join renderdatakse data-langs="de".
Atribuutide väli
Välja attributes kasutamisel pole atribuuti set vaja, sest väli seostab väärtused automaatselt atribuudi nime ja väärtusega.
Laienduse väljade uurimine
bs_block_extension_fields('core/paragraph') tagastab kõigi plokiga sobivate laienduste väljade määratlused. Tagastusväärtuse ja selle seose kohta bs_block_fields()-ga vaadake jaotist Plokkide uurimine.