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

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

Типы пользовательских полей позволяют теме или плагину добавлять новые элементы управления полями Blockstudio. Они отличаются от пользовательских полей:

  • custom/{name} ссылается на повторно используемую группу существующих полей.
  • namespace/type-name использует зарегистрированный тип поля с собственным элементом управления редактора и формой значения.

Blockstudio предоставляет систему регистрации. Элемент управления поставляется вместе с вашей темой или плагином.

Когда их использовать

Используйте пользовательский тип поля, если проекту нужен специализированный элемент управления для редактирования, который должен везде вести себя как встроенное поле Blockstudio:

  • атрибуты блока
  • повторно используемые группы полей custom/{name}
  • группы, вкладки и повторители
  • шаблоны PHP, Twig и Blade
  • метаданные записей и хранилище параметров
  • шаблоны расширений, такие как {attributes.margin.top}

Например, элемент управления интервалами может хранить один объект вместо четырех отдельных текстовых полей:

JSON
{
  "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:

Text
namespace/type-name

Допустимые примеры:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Зарезервированные пространства имен:

  • custom/ зарезервировано для повторно используемых групп пользовательских полей.
  • blockstudio/ зарезервировано для ядра Blockstudio.

Недопустимые имена игнорируются фильтром API и отклоняются помощником API.

Регистрация PHP

Зарегистрируйте метаданные типа поля в 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:

PHP
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переносимые ссылки на медиафайлы.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

Регистрация JavaScript

Скрипт редактора регистрирует соответствующий элемент управления React:

JavaScript
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, если регистрация принята. Удалите регистрацию на стороне клиента с помощью:

JavaScript
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

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

В шаблонах расширений также работают вложенные пути объектов:

JSON
{
  "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.

JSON
{
  "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 создаст блоки.