Przejdź do treści

Niestandardowe typy pól

Niestandardowe typy pól pozwalają motywowi lub wtyczce dodawać nowe kontrolki pól Blockstudio. Różnią się od pól niestandardowych:

  • custom/{name} odnosi się do grupy istniejących pól wielokrotnego użytku.
  • namespace/type-name używa zarejestrowanego typu pola z własną kontrolką edytora i strukturą wartości.

Blockstudio dostarcza system rejestracji. Kontrolkę dostarcza motyw lub wtyczka.

Kiedy ich używać

Użyj niestandardowego typu pola, gdy projekt wymaga kontrolki edycji o jednym konkretnym zastosowaniu, która powinna wszędzie działać jak natywne pole Blockstudio:

  • atrybuty bloków
  • wielokrotnego użytku grupy pól custom/{name}
  • grupy, karty i powtarzacze
  • szablony PHP, Twig i Blade
  • metadane wpisów i przechowywanie opcji
  • szablony rozszerzeń, takie jak {attributes.margin.top}

Na przykład kontrolka odstępów może przechowywać jeden obiekt zamiast czterech osobnych pól tekstowych:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Nazewnictwo

Nazwy niestandardowych typów pól muszą być zapisane małymi literami, mieć przestrzeń nazw i format dashcase:

Text
namespace/type-name

Prawidłowe przykłady:

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

Zarezerwowane przestrzenie nazw:

  • custom/ jest zarezerwowane dla grup niestandardowych pól wielokrotnego użytku.
  • blockstudio/ jest zarezerwowane dla rdzenia Blockstudio.

Nieprawidłowe nazwy są ignorowane przez filtr API i odrzucane przez funkcję pomocniczą API.

Rejestracja PHP

Zarejestruj metadane typu pola w 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() zwraca true, gdy rejestracja się powiedzie, i false, gdy nazwa lub definicja jest nieprawidłowa. Ręczną rejestrację można wyrejestrować za pomocą bs_unregister_field_type().

Możesz również użyć filtra API:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

Klucze definicji

Klucz Typ Opis
attribute string, array, null Typ atrybutu WordPress. Użyj string, number, boolean, object, array lub tablicy tych typów.
default mixed Domyślna wartość na poziomie rejestru, gdy pole nie definiuje własnej wartości domyślnej.
source string Źródło atrybutu WordPress dla niestandardowych przypadków serializacji.
produces_attribute boolean Ustaw na false w przypadku kontrolek tylko do wyświetlania. Domyślnie true.
editor_script string or array Zarejestrowany uchwyt skryptu lub uchwyty skryptów do wczytania w edytorze bloków, gdy używany jest ten typ.
editor_style string or array Zarejestrowany uchwyt stylu lub uchwyty stylów do wczytania w edytorze bloków, gdy używany jest ten typ.
storage array Typ przechowywanej wartości i wskazówki schematu REST dla metadanych wpisów i opcji.
supports array Opcjonalne flagi możliwości dla własnej kontrolki.
translate boolean Ustaw na true, gdy wartość jest tekstem do przetłumaczenia przez WPML. Wymaga attribute string.

Definicja z wartością translate, która nie jest wartością logiczną, lub z translate ustawionym na true i attribute innym niż string, jest nieprawidłowa. bs_register_field_type() zwraca false, a filtr API ją pomija.

WPML

wp bs wpml config nie może na podstawie samej rejestracji stwierdzić, czy wartość niestandardowego typu pola jest tekstem, więc pomija takie pola i wyświetla ostrzeżenie dla każdego z nich. Ustaw translate na true w rejestracji typu pola, który przechowuje zwykły tekst, a polecenie zadeklaruje jego pola tak jak pola text. Pole nadal może zostać wykluczone za pomocą "translate": false. Zobacz dokumentacjęWPML.

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

Rejestracja JavaScript

Skrypt edytora rejestruje pasującą kontrolkę 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() zwraca true, gdy rejestracja zostanie zaakceptowana. Rejestrację po stronie klienta usuń za pomocą:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

Komponent otrzymuje właściwości definicji pola oraz następujące niezmienne właściwości:

Właściwość Opis
type Nazwa typu pola.
id ID pola.
field Pełna definicja pola z block.json.
value Aktualnie zapisana wartość.
defaultValue Domyślna wartość pola.
onChange Bezpośredni zapis nowej wartości.
attributes Aktualne atrybuty bloku.
block Definicja aktualnego typu bloku.
clientId ID klienta aktualnego bloku edytora.
inRepeater Czy pole znajduje się w wierszu powtarzacza.
repeaterId Aktualna ścieżka powtarzacza, jeśli istnieje.
disabled Czy pole jest wyłączone w edytorze.

Wartości niestandardowych typów pól są przechowywane bezpośrednio. Nie przechodzą przez normalizację opcji select, radio, color ani gradient.

Renderowanie wartości

Wartości obiektów są dostępne tak samo jak każdy inny atrybut 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>

Zagnieżdżone ścieżki obiektów działają również w szablonach rozszerzeń:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Przechowywanie

Gdy niestandardowy typ pola jest używany z przechowywaniem postMeta lub option, Blockstudio używa zarejestrowanego typu przechowywanej wartości i schematu REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

W przypadku wartości array i object zdefiniuj storage.rest_schema w rejestracji typu pola. Potomkowie powtarzacza nadal korzystają z przechowywania opartego na tablicach, ponieważ powtarzacz przechowuje wiersze.

Zachowanie awaryjne

Jeśli PHP rozpoznaje typ pola, ale skrypt edytora nie rejestruje pasującej kontrolki, Blockstudio zachowuje zapisaną wartość i wyświetla w edytorze nieedytowalne powiadomienie. Renderowanie na froncie nadal otrzymuje zapisaną wartość.

Jeśli typ pola nie jest zarejestrowany w PHP, Blockstudio pomija go w wygenerowanych atrybutach WordPress. Zarejestruj definicję PHP przed uruchomieniem wykrywania bloków, zwykle w init, zanim Blockstudio zbuduje bloki.