Типове персонализирани полета
Типовете персонализирани полета позволяват на тема или добавка да добавя нови 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"
}
}
]
}
}
Именуване
Имената на типовете персонализирани полета трябва да са с малки букви, да имат пространство от имена и да използват тирета:
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 да създаде блоковете.