Tipos de campos personalizados
Os tipos de campos personalizados permitem que um tema ou plugin adicione novos controles de campos Blockstudio. Eles são diferentes dos campos personalizados:
custom/{name}faz referência a um grupo reutilizável de campos existentes.namespace/type-nameusa um tipo de campo registrado, com seu próprio controle de editor e formato de valor.
Blockstudio fornece o sistema de registro. Seu tema ou plugin fornece o controle.
Quando usá-los
Use um tipo de campo personalizado quando um projeto precisar de um controle de edição específico que deva se comportar como um campo nativo do Blockstudio em todos os contextos:
- atributos de bloco
- grupos de campos
custom/{name}reutilizáveis - grupos, abas e repetidores
- modelos de PHP, Twig e Blade
- armazenamento de metadados do post e de opções
- modelos de extensão como
{attributes.margin.top}
Por exemplo, um controle de espaçamento pode armazenar um objeto em vez de quatro campos de texto separados:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Nomenclatura
Os nomes dos tipos de campos personalizados devem estar em minúsculas, ter um namespace e usar palavras separadas por hífens:
namespace/type-name
Exemplos válidos:
acme/dimensionsacme/text-optionstheme/spacing-token
Namespaces reservados:
custom/é reservado para grupos reutilizáveis de campos personalizados.blockstudio/é reservado para o núcleo do Blockstudio.
Nomes inválidos são ignorados pelo filtro API e rejeitados pelo auxiliar API.
Registro de PHP
Registre os metadados do tipo de campo em 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() retorna true quando o registro é bem-sucedido e false quando o nome ou a definição é inválido. Você pode cancelar um registro manual com bs_unregister_field_type().
Você também pode usar o filtro API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Chaves de definição
| Chave | Tipo | Descrição |
|---|---|---|
attribute |
string, array, null |
tipo de atributo WordPress. Use string, number, boolean, object, array ou um array desses tipos. |
default |
mixed | Padrão no nível do registro quando um campo não define seu próprio padrão. |
source |
string | Origem do atributo WordPress para casos de serialização personalizados. |
produces_attribute |
boolean | Defina como false para controles somente de exibição. O padrão é true. |
editor_script |
string or array | Identificador de script registrado ou identificadores a enfileirar no editor de blocos quando o tipo for usado. |
editor_style |
string or array | Identificador de estilo registrado ou identificadores a enfileirar no editor de blocos quando o tipo for usado. |
storage |
array | Tipo de valor de armazenamento e dicas de esquema REST para metadados de post e opções. |
supports |
array | Sinalizadores de capacidade opcionais para seu próprio controle. |
translate |
boolean | Defina como true quando o valor for texto para WPML traduzir. Requer attribute string. |
Uma definição com um valor translate que não seja booleano, ou com
translate definido como true e um attribute diferente de string, é inválida.
bs_register_field_type() retorna false e o filtro API a ignora.
WPML
wp bs wpml config não consegue determinar apenas pelo registro se o valor
de um tipo de campo personalizado é texto, então omite esses campos e exibe um
aviso para cada um. Defina translate como true no registro de um tipo de campo
que armazena uma string de texto simples, e o comando declara seus campos como
campos text. Ainda é possível excluir um campo com "translate": false. Consulte
WPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registro de JavaScript
O script do editor registra o controle React correspondente:
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() retorna true quando o registro é aceito. Remova um registro no cliente com:
window.blockstudio.unregisterFieldType('acme/dimensions');
O componente recebe as propriedades da definição do campo, além destas propriedades estáveis:
| Propriedade | Descrição |
|---|---|
type |
Nome do tipo de campo. |
id |
ID do campo. |
field |
Definição completa do campo de block.json. |
value |
Valor salvo no momento. |
defaultValue |
Valor padrão do campo. |
onChange |
Armazena diretamente um novo valor. |
attributes |
Atributos do bloco atual. |
block |
Definição do tipo de bloco atual. |
clientId |
ID do bloco no cliente do editor atual. |
inRepeater |
Indica se o campo está dentro de uma linha de repetidor. |
repeaterId |
Caminho atual do repetidor, se houver. |
disabled |
Indica se o campo está desativado no editor. |
Os valores de tipos de campos personalizados são armazenados diretamente. Eles não passam pela normalização de opções nativas de select, radio, color ou gradient.
Renderização de valores
Os valores de objetos ficam disponíveis como qualquer outro atributo 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>
Caminhos para objetos aninhados também funcionam em modelos de extensão:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Armazenamento
Quando um tipo de campo personalizado é usado com o armazenamento postMeta ou option, Blockstudio usa o tipo de valor de armazenamento registrado e o esquema REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Para valores array e object, defina storage.rest_schema no registro do tipo de campo. Os campos descendentes do repetidor continuam usando armazenamento baseado em arrays, pois um repetidor armazena linhas.
Comportamento alternativo
Se PHP reconhecer o tipo de campo, mas o script do editor não registrar um controle correspondente, Blockstudio mantém o valor salvo e exibe um aviso não editável no editor. A renderização no frontend continua recebendo o valor salvo.
Se um tipo de campo não estiver registrado em PHP, Blockstudio o omitirá dos atributos WordPress gerados. Registre a definição de PHP antes que a descoberta de blocos seja executada, geralmente em init antes que Blockstudio crie os blocos.