Pereiti prie turinio

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.

JSON
{
  "$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ą:

„View“ plėtinio schema

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:

JSON
{
  "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:

JSON
{
  "$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
JSON
{
  "$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:

JSON
{
  "$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ų.

JSON
{
  "$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.

JSON
{
  "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ę.

JSON
{
  "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.