Типи користувацьких полів
Типи користувацьких полів дають темі або плагіну змогу додавати нові елементи керування полями 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"
}
}
]
}
}
Іменування
Назви типів користувацьких полів мають бути в нижньому регістрі, з простором імен і в dashcase:
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 створить блоки.