Към съдържанието

Разширения

Разширенията ви позволяват да разширите всеки регистриран блок във вашата инсталация на WordPress чрез проста конфигурация .json, базирана на API и подобна на конфигурацията block.json. Това включва основните блокове, блокове на трети страни и блокове, създадени с Blockstudio.

Всички типове полета могат да се добавят към всеки блок, а данните се записват в атрибутите му. За разширенията са достъпни всички възможности на атрибутите, като филтриране, деактивиране, условна логика и попълване на опции.

Видове разширения

Разширените стойности могат да се използват по различни начини:

  • class: Добавя клас към блока чрез стойността на атрибута
  • style: Добавя вградени стилове към блока чрез стойността на атрибута
  • attributes: Задава директно стойността на всеки атрибут на блока
  • data attributes: Използва стойностите на разширението, за да задава конкретни атрибути за данни

Настройка

Представете си следния сценарий: искате да добавите поле select за персонализиран клас към всеки основен блок. Достатъчно е да добавите този файл .json където и да е в папката с блокове и той автоматично ще бъде регистриран като разширение.

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

Това ще добави поле customColor към всеки основен блок, за да можете да задавате цвета на текста в блока.

Име на файла

Тъй като няма шаблон за визуализиране, разширението не се нуждае от съответстващ файл index и не е необходимо да се казва block.json. Така всички разширения могат удобно да се съхраняват в една папка. Няколко файла могат да разширяват едни и същи блокове, например два файла с "name": "core/*"; всеки регистрира свои полета.

Схема

Blockstudio предоставя персонализирана схема JSON за конфигурациите на разширенията:

Преглед на схемата на разширението

Име

Свойството name на конфигурационния обект определя кои блокове да бъдат разширени. Има три възможности според нуждите ви:

  • blockName: Името на един блок, e.g. core/paragraph
  • [blockNameA, blockNameB]: Масив с имена на блокове, e.g. ["core/paragraph", "core/heading"]
  • core/*: Заместващ знак за разширяване на всички блокове от определен тип

Всяко име, завършващо със звездичка, е заместващ знак за префикс, а не само core/*. Следното разширение важи за всеки блок, чието име започва с my-plugin/, включително блокове, създадени с Blockstudio:

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

Изключване на блокове

Използвайте масив exclude на най-горно ниво, за да пропуснете блокове, които иначе биха съвпаднали с name:

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

Изключванията използват същото съвпадение по точно име и по префикс с крайно * като name. Те имат предимство пред отделни имена, списъци с имена и заместващи знаци. На изключен блок не се добавят нито полетата на редактора, нито атрибутите или ресурсите на фронтенда на разширението. Други съвпадащи разширения не се засягат. Пропуснете exclude или използвайте празен масив, за да запазите текущото поведение.

Ключ Blockstudio

Както и при използването на block.json за персонализирани блокове, свойството blockstudio трябва да присъства в конфигурационния обект, като extend е зададено на true.

Позиция

По подразбиране разширенията се показват в собствен раздел в инспектора на блока. Ако искате да преместите разширенията на друга позиция, можете да използвате свойството group:

  • settings: Позицията по подразбиране
  • styles: Разделът за стилове
  • advanced: Разделът за разширени настройки
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Приоритет

Свойството priority ви позволява да зададете реда, в който се показват разширенията. Разширенията с по-висок приоритет се показват по-късно. Задайте го на най-горно ниво във файла, както в примера за настройка, или в extend:

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

Когато са зададени и двете, предимство има blockstudio.extend.priority.

Атрибути

За повече информация за работата на атрибутите вижте раздела за атрибутите.

Единственото, което трябва да знаете за атрибутите в разширенията, е свойството set. То се използва, за да приложи стойността на атрибута към един от типовете разширения.

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

Получаване на стойности

За да получите стойността на атрибут, използвайте точкова нотация във фигурни скоби.

Можете да получавате и вложени стойности, когато атрибутите не връщат единична стойност, например когато задавате формата на връщаната стойност на 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}"
        }
      ]
    }
  ]
}

Примерът по-горе ще зададе атрибута style на color: #f00 или color: #00f, а атрибута data-color — на Red или Blue според стойността.

Засега в дефинициите на set могат да се използват само стойности от текущия атрибут. Възможността за използване на стойности от други атрибути може да бъде добавена в бъдеще.

Масиви

При работа с масиви свойството set се прилага към всеки елемент в масива.

Всеки елемент добавя собствен клас или декларация за стил. Всеки друг атрибут съдържа една стойност, затова всеки елемент я презаписва и последният има предимство. Задайте join на true, за да записвате вместо това резултатите от всички елементи, разделени с интервали и без празни или повтарящи се стойности, така че селектор като [data-langs~="en"] да съвпада с всеки избран елемент. join няма ефект върху class и style, нито върху полета, които връщат единична стойност.

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

Избирането на двете опции визуализира data-langs="en de". Без join визуализира data-langs="de".

Поле за атрибути

При използване на полето attributes не е необходимо свойство set, тъй като полето автоматично съпоставя стойностите с името и стойността на атрибута.

Преглед на полетата на разширенията

bs_block_extension_fields('core/paragraph') връща дефинициите на полетата на всяко разширение, което съвпада с даден блок. Вижте Преглед на блокове за върнатата стойност и връзката ѝ с bs_block_fields().