Пользовательские поля
Пользовательские поля позволяют определять повторно используемые группы полей, на которые можно ссылаться в нескольких блоках. Представьте их как шаблоны полей: определите один раз и используйте где угодно.
Пользовательские поля — это не то же самое, что
типы пользовательских полей. Используйте
custom/{name} для повторно используемых групп существующих полей. Используйте пользовательский тип поля с пространством имен, например acme/dimensions, когда тема или плагин регистрирует новый элемент управления редактора и форму значения.
Регистрация в файловой системе
Создайте файл field.json в каталоге fields/ внутри каталога blockstudio:
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.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:
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}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Это разворачивает поля, заданные в определении пользовательского поля, прямо в строке. Развернутые поля сохраняют исходные ID (heading, description, enabled).
Пользовательские поля также могут повторно использовать полные определения групп:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
Дочерние элементы группы сохраняются как section-header_kicker,
section-header_title и так далее. В шаблонах используйте bs_get_group(), чтобы
извлечь их в удобный объект группы.
Структура ID
Используйте idStructure как префикс или для преобразования ID полей. Заполнитель {id} заменяется исходным ID поля:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
В результате получаются поля с ID: hero_heading, hero_description, hero_enabled.
Переопределение значений
Настраивайте отдельные поля для каждого экземпляра с помощью overrides. Ключи — это исходные ID полей из определения:
{
"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 группы. Условия ссылки добавляются после этого.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
В этом блоке доступны только White и Grey, сколько бы вариантов ни было перечислено в определении.
Условия
Условия внутри определений пользовательских полей автоматически переписываются при применении idStructure. Поле, условно зависящее от соседнего поля, продолжает работать после развертывания.
{
"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 }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio разворачивает это в title_font_enable, title_font_min,
title_font_max и переписывает условия так, чтобы они ссылались на
title_font_enable вместо enable. Переключатели работают
точно так же, как если бы поля были заданы в строке.
Условия на уровне ссылки
Добавьте conditions к ссылке, чтобы применить их ко всем развернутым полям. Это
полезно, чтобы скрыть целую группу за внешним переключателем:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Эти условия объединяются с уже заданными в определении поля. ID условий также переписываются через idStructure.
Несколько пользовательских полей
В одном блоке можно использовать несколько пользовательских полей вместе с обычными полями:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Вложенность
Пользовательские поля работают внутри групп, вкладок и повторителей:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Дополнительные пути обнаружения
Используйте фильтр blockstudio/fields/paths, чтобы добавить каталоги для поиска полей:
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, существуют во время выполнения и не могут быть выведены
статически.