Treci la conținut

Extensii

Extensiile vă permit să extindeți orice bloc înregistrat în instalarea WordPress folosind o .json simplă, bazată pe API, similară configurației block.json. Aceasta include blocurile de bază, ale terților și cele create cu Blockstudio.

Toate tipurile de câmpuri pot fi adăugate la orice bloc, iar datele sunt salvate în atributele blocului. Setul complet de funcționalități ale atributelor, precum filtrarea, dezactivarea, logica condițională și popularea opțiunilor, este disponibil pentru extensii.

Tipuri de extensii

Valorile extinse pot fi utilizate în mai multe moduri:

  • class: Adăugați o clasă blocului folosind valoarea atributului
  • style: Adăugați stiluri inline blocului folosind valoarea atributului
  • attributes: Setați direct orice valoare de atribut a blocului
  • data attributes: Folosiți valorile extensiei pentru a seta anumite atribute de date

Configurare

Imaginează-ți următorul scenariu: vrei să adaugi un câmp select pentru o clasă personalizată fiecărui bloc de bază. Tot ce trebuie să faci este să adaugi acest fișier .json oriunde în dosarul blocului, iar acesta va fi înregistrat automat ca extensie.

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}"
          }
        ]
      }
    ]
  }
}

Aceasta va adăuga un câmp customColor fiecărui bloc de bază, permițându-ți să setezi culoarea textului blocului.

Nume fișier

Deoarece nu există un șablon de randare, o extensie nu are nevoie de un fișier index corespunzător și, prin urmare, nu trebuie să se numească block.json. Astfel, toate extensiile pot fi stocate comod într-un singur dosar. Mai multe fișiere pot extinde aceleași blocuri, de exemplu două fișiere cu "name": "core/*"; fiecare își înregistrează propriile câmpuri.

Schemă

Blockstudio oferă o schemă JSON personalizată pentru configurațiile extensiilor:

Schemă extensie View

Nume

Proprietatea name a obiectului de configurare definește blocurile care trebuie extinse. Există trei opțiuni, în funcție de necesități:

  • blockName: Un singur nume de bloc, e.g. core/paragraph
  • [blockNameA, blockNameB]: O matrice de nume de blocuri, e.g. ["core/paragraph", "core/heading"]
  • core/*: Un wildcard pentru extinderea tuturor blocurilor de un anumit tip

Orice nume care se termină cu un asterisc este un wildcard de prefix, nu doar core/*. Extensia următoare se aplică fiecărui bloc al cărui nume începe cu my-plugin/, inclusiv blocurilor create cu Blockstudio:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Excluderea blocurilor

Folosiți un tablou exclude de nivel superior pentru a omite blocurile care altfel s-ar potrivi cu name:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Excluderile folosesc aceeași potrivire după nume exact și după prefixul cu * la final ca name. Au prioritate față de numele individuale, listele de nume și wildcarduri. Un bloc exclus nu primește nici câmpurile de editor ale extensiei, nici atributele sau resursele frontend. Celelalte extensii potrivite nu sunt afectate. Omiteți exclude sau folosiți un tablou gol pentru a păstra comportamentul existent.

Cheia Blockstudio

La fel ca atunci când folosești block.json pentru blocuri personalizate, proprietatea blockstudio trebuie să fie prezentă în obiectul de configurare, cu extend setat la true.

Poziție

În mod implicit, extensiile sunt afișate într-o filă proprie în inspectorul blocului. Dacă vrei să le muți într-o altă poziție, poți folosi proprietatea group:

  • settings: Poziția implicită
  • styles: Fila de stiluri
  • advanced: Fila pentru opțiuni avansate
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Prioritate

Proprietatea priority îți permite să definești ordinea în care sunt afișate extensiile. Extensiile cu prioritate mai mare vor fi afișate mai târziu. Seteaz-o la nivelul superior al fișierului, ca în exemplul de configurare, sau în extend:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

Când sunt setate ambele, blockstudio.extend.priority are prioritate.

Atribute

Pentru mai multe informații despre funcționarea atributelor, consultă secțiunea despre atribute.

Singurul lucru pe care trebuie să-l știi despre atributele din extensii este proprietatea set. Aceasta este folosită pentru a aplica valoarea atributului unuia dintre tipurile de extensii.

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}"
          }
        ]
      }
    ]
  }
}

Obținerea valorilor

Notația cu punct în interiorul acoladelor este folosită pentru a obține valoarea unui atribut.

De asemenea, poți obține valori imbricate atunci când atributele nu returnează o singură valoare, de exemplu când setezi formatul de returnare la both pentru tipuri de câmp cu opțiuni.

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}"
        }
      ]
    }
  ]
}

Exemplul de mai sus va seta atributul style la color: #f00 sau color: #00f și atributul data-color la Red sau Blue, în funcție de valoare.

Deocamdată, în definițiile set pot fi folosite doar valorile atributului curent. Posibilitatea de a folosi valori din alte atribute ar putea fi adăugată în viitor.

Matrice

Când folosești matrice, proprietatea set se aplică fiecărui element din matrice.

Fiecare element adaugă propria clasă sau declarație de stil. Orice alt atribut conține o singură valoare, așa că fiecare element îl suprascrie, iar ultimul are prioritate. Setați join la true pentru a scrie în schimb rezultatele tuturor elementelor, separate prin spații și fără valori goale sau repetate, astfel încât un selector precum [data-langs~="en"] să se potrivească cu fiecare element ales. join nu are efect asupra class și style sau asupra câmpurilor care returnează o singură valoare.

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
    }
  ]
}

Alegerea ambelor opțiuni redă data-langs="en de". Fără join, redă data-langs="de".

Câmpul Attributes

Când folosești câmpul attributes, proprietatea set nu este necesară, deoarece câmpul asociază automat valorile cu numele și valoarea atributului.

Inspectarea câmpurilor extensiilor

bs_block_extension_fields('core/paragraph') returnează definițiile câmpurilor pentru fiecare extensie care se potrivește cu un bloc. Consultați Inspectarea blocurilor pentru valoarea returnată și modul în care se raportează la bs_block_fields().