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-nameuż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:
{
"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:
namespace/type-name
Prawidłowe przykłady:
acme/dimensionsacme/text-optionstheme/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:
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:
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.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Rejestracja JavaScript
Skrypt edytora rejestruje pasującą kontrolkę 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() zwraca true, gdy rejestracja zostanie zaakceptowana. Rejestrację po stronie klienta usuń za pomocą:
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
<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>
Zagnieżdżone ścieżki obiektów działają również w szablonach rozszerzeń:
{
"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.
{
"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.