Перейти к содержимому

Пользовательские поля

Пользовательские поля позволяют определять повторно используемые группы полей, на которые можно ссылаться в нескольких блоках. Представьте их как шаблоны полей: определите один раз и используйте где угодно.

Пользовательские поля — это не то же самое, что типы пользовательских полей. Используйте custom/{name} для повторно используемых групп существующих полей. Используйте пользовательский тип поля с пространством имен, например acme/dimensions, когда тема или плагин регистрирует новый элемент управления редактора и форму значения.

Регистрация в файловой системе

Создайте файл field.json в каталоге fields/ внутри каталога blockstudio:

Код
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

Регистрация через фильтр PHP

Регистрируйте пользовательские поля программно с помощью фильтра blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

Использование в block.json

Ссылайтесь на пользовательское поле с помощью типа custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Это разворачивает поля, заданные в определении пользовательского поля, прямо в строке. Развернутые поля сохраняют исходные ID (heading, description, enabled).

Пользовательские поля также могут повторно использовать полные определения групп:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Дочерние элементы группы сохраняются как section-header_kicker, section-header_title и так далее. В шаблонах используйте bs_get_group(), чтобы извлечь их в удобный объект группы.

Структура ID

Используйте idStructure как префикс или для преобразования ID полей. Заполнитель {id} заменяется исходным ID поля:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

В результате получаются поля с ID: hero_heading, hero_description, hero_enabled.

Переопределение значений

Настраивайте отдельные поля для каждого экземпляра с помощью overrides. Ключи — это исходные ID полей из определения:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Переопределенные свойства объединяются с исходным определением поля. Переопределение id обходит шаблон idStructure. В примере выше enabled становится active вместо hero_enabled.

Слияние выполняется только на один уровень: переопределяемое свойство заменяет исходное свойство целиком. Переопределение options — это полный список параметров, а не добавление к нему; то же относится к conditions и к attributes группы. Условия ссылки добавляются после этого.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

В этом блоке доступны только White и Grey, сколько бы вариантов ни было перечислено в определении.

Условия

Условия внутри определений пользовательских полей автоматически переписываются при применении idStructure. Поле, условно зависящее от соседнего поля, продолжает работать после развертывания.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio разворачивает это в title_font_enable, title_font_min, title_font_max и переписывает условия так, чтобы они ссылались на title_font_enable вместо enable. Переключатели работают точно так же, как если бы поля были заданы в строке.

Условия на уровне ссылки

Добавьте conditions к ссылке, чтобы применить их ко всем развернутым полям. Это полезно, чтобы скрыть целую группу за внешним переключателем:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Эти условия объединяются с уже заданными в определении поля. ID условий также переписываются через idStructure.

Несколько пользовательских полей

В одном блоке можно использовать несколько пользовательских полей вместе с обычными полями:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Вложенность

Пользовательские поля работают внутри групп, вкладок и повторителей:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Дополнительные пути обнаружения

Используйте фильтр blockstudio/fields/paths, чтобы добавить каталоги для поиска полей:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Статический анализ

Пакет blockstudio/phpstan разворачивает ссылки custom/*, заданные в файлах, при проверке PHP, Twig, Blade, тегов блоков и выведенных форм атрибутов. При развертывании соблюдаются те же правила вложенности, idStructure и overrides, описанные выше.

Для определений вне анализируемого проекта добавьте каталог библиотеки в blockstudioScanRoots в phpstan.neon. Поля, зарегистрированные только через фильтр blockstudio/fields PHP, существуют во время выполнения и не могут быть выведены статически.