Към съдържанието

Типове персонализирани полета

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

Именуване

Имената на типовете персонализирани полета трябва да са с малки букви, да имат пространство от имена и да използват тирета:

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 да създаде блоковете.