
# Расширения

Расширения позволяют дополнять любой зарегистрированный блок в вашей установке WordPress с помощью простой конфигурации API на основе `.json`, похожей на конфигурацию `block.json`. Это относится к основным блокам, сторонним блокам и блокам, созданным с помощью Blockstudio.

Для любого блока можно добавлять все типы полей [field types](https://blockstudio.dev/ru/docs/blocks/attributes/field-types/); данные сохраняются в атрибутах блока. Для расширений доступны все возможности полей, включая [фильтрацию](https://blockstudio.dev/ru/docs/blocks/attributes/filtering/), [отключение](https://blockstudio.dev/ru/docs/blocks/attributes/disabling/), [условную логику](https://blockstudio.dev/ru/docs/blocks/attributes/conditional-logic/) и [заполнение вариантов](https://blockstudio.dev/ru/docs/blocks/attributes/populating-options/).

## Типы расширений

Значения расширений можно применять разными способами:

- **class**: добавление классу блока значения атрибута
- **style**: добавление встроенных стилей блоку с помощью значения атрибута
- **attributes**: непосредственная установка значения любого атрибута блока
- **data attributes**: использование значений расширения для задания определённых атрибутов данных

## Настройка

Представьте такой сценарий: вы хотите добавить поле `select` для пользовательского класса в каждый основной блок. Достаточно добавить этот файл `.json` в любое место папки блока, и он автоматически зарегистрируется как расширение.

```json title="core.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 для конфигураций расширений:

[Схема расширения Meta Box View](https://blockstudio.dev/schema/extend)

### Имя

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

- **blockName**: имя одного блока, e.g. `core/paragraph`
- **[blockNameA, blockNameB]**: массив имен блоков, e.g. `["core/paragraph", "core/heading"]`
- **core/\***: подстановочный шаблон для расширения всех блоков определенного типа

Любое имя, оканчивающееся звездочкой, задает подстановку префикса, а не только `core/*`. Следующее расширение применяется ко всем блокам, имена которых начинаются с `my-plugin/`,
включая блоки, созданные с помощью Blockstudio:

```json title="extension.json"
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}
```

### Исключение блоков

Чтобы пропускать блоки, которые иначе соответствовали бы `name`, используйте массив `exclude` верхнего уровня:

```json title="extension.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 title="core.json"
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}
```

### Приоритет

Свойство `priority` позволяет задать порядок отображения расширений. Расширения с более высоким приоритетом отображаются позже. Укажите его на верхнем уровне файла, как в примере настройки, или внутри `extend`:

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

Если заданы оба значения, приоритет имеет `blockstudio.extend.priority`.

## Атрибуты

Подробнее о работе атрибутов см. в [разделе об атрибутах](https://blockstudio.dev/ru/docs/blocks/attributes/field-types/).

Единственное, что нужно знать об атрибутах расширений, — это свойство `set`. Оно используется, чтобы передать значение атрибута одному из [типов расширений](#extension-types).

```json title="core.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

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

## Просмотр полей расширений

`bs_block_extension_fields('core/paragraph')` возвращает определения полей
всех расширений, соответствующих блоку. Подробнее о возвращаемом
значении и его связи с `bs_block_fields()` см. в разделе [Просмотр блоков](https://blockstudio.dev/ru/docs/blocks/rendering/#inspecting-blocks).
