Типы пользовательских полей
Типы пользовательских полей позволяют теме или плагину добавлять новые элементы управления полями Blockstudio. Они отличаются от пользовательских полей:
custom/{name}ссылается на повторно используемую группу существующих полей.namespace/type-nameиспользует зарегистрированный тип поля с собственным элементом управления редактора и формой значения.
Blockstudio предоставляет систему регистрации. Элемент управления поставляется вместе с вашей темой или плагином.
Когда их использовать
Используйте пользовательский тип поля, если проекту нужен специализированный элемент управления для редактирования, который должен везде вести себя как встроенное поле Blockstudio:
- атрибуты блока
- повторно используемые группы полей
custom/{name} - группы, вкладки и повторители
- шаблоны PHP, Twig и Blade
- метаданные записей и хранилище параметров
- шаблоны расширений, такие как
{attributes.margin.top}
Например, элемент управления интервалами может хранить один объект вместо четырех отдельных текстовых полей:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Имена
Имена пользовательских типов полей должны состоять из строчных букв, иметь пространство имен и использовать kebab-case:
namespace/type-name
Допустимые примеры:
acme/dimensionsacme/text-optionstheme/spacing-token
Зарезервированные пространства имен:
custom/зарезервировано для повторно используемых групп пользовательских полей.blockstudio/зарезервировано для ядра Blockstudio.
Недопустимые имена игнорируются фильтром API и отклоняются помощником API.
Регистрация PHP
Зарегистрируйте метаданные типа поля в PHP:
add_action('init', function () {
wp_register_script(
'acme-field-dimensions',
get_stylesheet_directory_uri() . '/fields/dimensions.js',
['blockstudio-blocks', 'wp-components', 'wp-element'],
'1.0.0',
true
);
bs_register_field_type('acme/dimensions', [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
'storage' => [
'type' => 'object',
'rest_schema' => [
'type' => 'object',
'additionalProperties' => ['type' => 'string'],
],
],
]);
});
bs_register_field_type() возвращает true при успешной регистрации и false,
если имя или определение недопустимы. Отменить регистрацию вручную можно с помощью
bs_unregister_field_type().
Также можно использовать фильтр API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Ключи определения
| Ключ | Тип | Описание |
|---|---|---|
attribute |
string, array, null |
Тип атрибута WordPress. Используйте string, number, boolean, object, array или массив из этих типов. |
default |
mixed | Значение по умолчанию на уровне реестра, если для поля не задано собственное значение. |
source |
string | Источник атрибута WordPress для пользовательских случаев сериализации. |
produces_attribute |
boolean | Установите false для элементов управления только для отображения. По умолчанию — true. |
editor_script |
string or array | Зарегистрированный идентификатор скрипта или массив идентификаторов для подключения в редакторе блоков при использовании этого типа. |
editor_style |
string or array | Зарегистрированный идентификатор стиля или массив идентификаторов для подключения в редакторе блоков при использовании этого типа. |
storage |
array | Тип значения для хранения и подсказки схемы REST для метаданных записей и параметров. |
supports |
array | Необязательные флаги возможностей для собственного элемента управления. |
translate |
boolean | Установите true, если значение представляет собой текст для перевода в WPML. Требуются attribute string. |
Определение недопустимо, если значение translate не является логическим или если translate установлено в true, а значение attribute отличается от string.
bs_register_field_type() возвращает false, а фильтр API игнорирует его.
WPML
wp bs wpml config не может определить только по регистрации, является ли значение пользовательского типа поля текстом, поэтому пропускает такие поля и выводит предупреждение для каждого из них. Установите translate в значение true при регистрации типа поля, в котором хранится обычная текстовая строка. Тогда команда будет объявлять его поля как поля типа text. Для поля по-прежнему можно отключить это поведение с помощью "translate": false. Подробнее: WPMLпереносимые ссылки на медиафайлы.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Регистрация JavaScript
Скрипт редактора регистрирует соответствующий элемент управления React:
const { createElement: el } = wp.element;
const { TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/dimensions', {
component(props) {
const value =
props.value &&
typeof props.value === 'object' &&
!Array.isArray(props.value)
? props.value
: {};
const sides = props.sides || ['top', 'right', 'bottom', 'left'];
return el(
'div',
{},
sides.map((side) =>
el(TextControl, {
key: side,
label: side,
value: value[side] || '',
onChange(nextValue) {
props.onChange({
...value,
[side]: nextValue,
});
},
}),
),
);
},
});
registerFieldType() возвращает true, если регистрация принята. Удалите регистрацию на стороне клиента с помощью:
window.blockstudio.unregisterFieldType('acme/dimensions');
Компонент получает свойства определения поля и следующие стабильные свойства:
| Свойство | Описание |
|---|---|
type |
Имя типа поля. |
id |
ID поля. |
field |
Полное определение поля из block.json. |
value |
Текущее сохраненное значение. |
defaultValue |
Значение поля по умолчанию. |
onChange |
Сохранить новое значение напрямую. |
attributes |
Текущие атрибуты блока. |
block |
Текущее определение типа блока. |
clientId |
Текущий клиентский ID блока редактора. |
inRepeater |
Находится ли поле внутри строки повторителя. |
repeaterId |
Текущий путь повторителя, если есть. |
disabled |
Отключено ли поле в редакторе. |
Значения пользовательских типов полей сохраняются напрямую. Они не проходят нормализацию параметров встроенных select, radio, color или gradient.
Отображение значений
Значения объектов доступны как и любые другие атрибуты Blockstudio.
PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
В шаблонах расширений также работают вложенные пути объектов:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Хранение
Когда пользовательский тип поля используется с хранилищем postMeta или option,
Blockstudio использует зарегистрированный тип сохраняемого значения и схему REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Для значений array и object задайте storage.rest_schema в регистрации типа поля. Потомки повторителя продолжают использовать хранение на основе массивов, поскольку повторитель хранит строки.
Резервное поведение
Если PHP знает тип поля, но скрипт редактора не регистрирует соответствующий элемент управления, Blockstudio сохраняет сохраненное значение и показывает в редакторе уведомление, доступное только для чтения. При отображении на сайте по-прежнему используется сохраненное значение.
Если тип поля не зарегистрирован в PHP, Blockstudio исключает его из сгенерированных атрибутов WordPress. Зарегистрируйте определение PHP до начала обнаружения блоков, обычно в init перед тем, как Blockstudio создаст блоки.