Plėtiniai
Plėtiniai leidžia išplėsti bet kurį registruotą bloką jūsų WordPress įdiegtyje, naudojant paprastą .json pagrindu veikiančią API, panašią į block.json konfigūraciją. Tai apima pagrindinius ir trečiųjų šalių blokus, taip pat su Blockstudio sukurtus blokus.
Visus laukų tipus galima pridėti prie bet kurio bloko, o duomenys išsaugomi bloko atributuose. Plėtiniams prieinamos visos funkcijos: filtravimas, išjungimas, sąlyginė logika ir parinkčių pildymas.
Plėtinių tipai
Išplėstines reikšmes galima naudoti įvairiais būdais:
- klasė: pridėti blokui klasę, naudojant atributo reikšmę
- stilius: pridėti blokui tiesioginius stilius, naudojant atributo reikšmę
- atributai: tiesiogiai nustatyti bet kurią bloko atributo reikšmę
- duomenų atributai: plėtinio reikšmėmis nustatyti konkrečius duomenų atributus
Nustatymas
Įsivaizduokite tokį scenarijų: norite prie kiekvieno pagrindinio bloko pridėti pasirinktinį klasės select lauką. Tereikia įdėti šį .json failą bet kurioje bloko aplanko vietoje, ir jis bus automatiškai užregistruotas kaip plėtinys.
{
"$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}"
}
]
}
]
}
}
Taip prie kiekvieno pagrindinio bloko bus pridėtas customColor laukas, kuriame galėsite nustatyti bloko teksto spalvą.
Failo pavadinimas
Kadangi atvaizdavimo šablono nėra, plėtiniui nereikia atitinkamo index failo, todėl jo pavadinimas neturi būti block.json. Taip visus plėtinius galima patogiai laikyti viename aplanke. Keli failai gali išplėsti tuos pačius blokus, pavyzdžiui, du failai su "name": "core/*"; kiekvienas jų užregistruoja savo laukus.
Schema
Blockstudio plėtinių konfigūracijoms pateikia pasirinktinę JSON schemą:
Pavadinimas
Konfigūracijos objekto savybė name nurodo, kuriuos blokus reikia išplėsti. Atsižvelgiant į poreikius, galimi trys variantai:
- blockName: vieno bloko pavadinimas, e.g.
core/paragraph - [blockNameA, blockNameB]: blokų pavadinimų masyvas, e.g.
["core/paragraph", "core/heading"] - core/*: pakaitos šablonas, skirtas išplėsti visus tam tikro tipo blokus
Bet kuris pavadinimas, pasibaigiantis žvaigždute, yra prefikso pakaitos simbolis, ne tik core/*. Toliau pateiktas plėtinys taikomas kiekvienam blokui, kurio pavadinimas prasideda my-plugin/, įskaitant blokus, sukurtus naudojant Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Blokų neįtraukimas
Naudokite aukščiausio lygio exclude masyvą, kad praleistumėte blokus, kurie kitu atveju atitiktų name:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Neįtraukimo taisyklėse naudojamas toks pat tikslus pavadinimų ir galinio * prefikso atitikimas kaip ir name. Joms teikiama pirmenybė prieš pavienius pavadinimus, pavadinimų sąrašus ir pakaitos simbolius. Neįtrauktas blokas negauna nei plėtinio redaktoriaus laukų, nei jo sąsajos atributų ar išteklių. Kiti atitinkantys plėtiniai lieka nepaveikti. Praleiskite exclude arba naudokite tuščią masyvą, kad išliktų esama elgsena.
Blockstudio raktas
Kaip ir naudojant block.json pasirinktiniams blokams, konfigūracijos objekte turi būti savybė blockstudio, o jos reikšmė turi būti extend: true.
Vieta
Pagal numatytuosius nustatymus plėtiniai bloko inspektoriuje rodomi atskirame skirtuke. Jei norite juos perkelti į kitą vietą, galite naudoti savybę group:
- settings: numatytoji vieta
- styles: stilių skirtukas
- advanced: išplėstinių nustatymų skirtukas
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Prioritetas
Savybė priority leidžia nustatyti plėtinių atvaizdavimo tvarką. Didesnį prioritetą turintys plėtiniai atvaizduojami vėliau. Nustatykite ją failo aukščiausiame lygyje, kaip sąrankos pavyzdyje, arba extend viduje:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Jei nustatytos abi reikšmės, pirmenybė teikiama blockstudio.extend.priority.
Atributai
Daugiau informacijos apie atributų veikimą rasite atributų skiltyje.
Vienintelis dalykas, kurį reikia žinoti apie plėtinių atributus, yra savybė set. Ji naudojama atributo reikšmei pritaikyti vienam iš plėtinio tipų.
{
"$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}"
}
]
}
]
}
}
Reikšmių gavimas
Atributo reikšmei gauti naudojama taškinė žymėsena riestiniuose skliaustuose.
Taip pat galima gauti įdėtines reikšmes, kai atributai grąžina ne vieną reikšmę, pavyzdžiui, kai laukų tipams su parinktimis grąžinimo formatas nustatytas į both.
{
"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}"
}
]
}
]
}
Aukščiau pateiktame pavyzdyje atributui style bus nustatyta color: #f00 arba color: #00f reikšmė, o atributui data-color – Red arba Blue, atsižvelgiant į reikšmę.
Kol kas set aprašuose galima naudoti tik dabartinio atributo reikšmes. Galimybė naudoti kitų atributų reikšmes gali būti pridėta ateityje.
Masyvai
Naudojant masyvus, savybė set taikoma kiekvienam masyvo elementui.
Kiekvienas elementas prideda savo klasę arba stiliaus deklaraciją. Bet kuriame kitame atribute saugoma viena reikšmė, todėl kiekvienas elementas ją perrašo, o laimi paskutinis elementas. Nustatykite join į true, kad vietoj to būtų įrašyti visų elementų rezultatai, atskirti tarpais, be tuščių ar pasikartojančių reikšmių; taip parinkiklis, pavyzdžiui, [data-langs~="en"] atitiks kiekvieną pasirinktą elementą. join neturi poveikio class ir style, taip pat laukams, kurie grąžina vieną reikšmę.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
Pasirinkus abi parinktis, atvaizduojama data-langs="en de". Be join atvaizduojama data-langs="de".
Atributų laukas
Naudojant lauką attributes, savybės set nereikia, nes laukas automatiškai susieja reikšmes su atributo pavadinimu ir reikšme.
Plėtinio laukų tikrinimas
bs_block_extension_fields('core/paragraph') grąžina kiekvieno bloką atitinkančio plėtinio laukų apibrėžtis. Grąžinamą reikšmę ir jos ryšį su bs_block_fields() žr. skiltyje Blokų tikrinimas.