Перейти до вмісту

Типи користувацьких полів

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

Іменування

Назви типів користувацьких полів мають бути в нижньому регістрі, з простором імен і в dashcase:

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 створить блоки.