Criando um tipo de campo personalizado
Alguns valores são mais do que um primitivo. Um preço é composto por um valor e uma moeda. Com os campos integrados, você o modela como um campo numérico e um campo de seleção lado a lado, e cada bloco que exibe um preço repete o par, os rótulos e a lógica que os mantém juntos. Nos metadados do post, isso vira duas chaves; dentro de um repetidor, duas listas paralelas.
Um tipo de campo personalizado transforma o par em um só campo. Registre um tipo como
acme/price uma vez em PHP e em JavaScript, e depois use-o em qualquer
block.json como um campo nativo: no nível superior, dentro de grupos e
repetidores, com armazenamento nos metadados do post ou nas opções, e em modelos PHP, Twig e Blade.
Blockstudio deriva o atributo WordPress e o esquema de armazenamento REST
a partir do registro.
Isso é diferente de um campo personalizado.
Uma referência custom/{name} reutiliza um grupo de campos existentes. Um tipo de campo personalizado
adiciona um novo controle com seu próprio formato de valor.
Este guia cria acme/price de ponta a ponta: o registro de PHP, o controle do editor,
um bloco de preços que o usa no nível superior e dentro de um repetidor,
o armazenamento nos metadados do post com um esquema REST estrito e a saída renderizada.
Registrar o tipo em PHP
O lado PHP declara o tipo de atributo, o valor padrão, o script do editor que fornece o controle e como o valor é armazenado fora do bloco:
add_action( 'init', function () {
wp_register_script(
'acme-field-price',
get_stylesheet_directory_uri() . '/fields/price.js',
array( 'blockstudio-blocks', 'wp-components', 'wp-element' ),
'1.0.0',
true
);
bs_register_field_type( 'acme/price', array(
'attribute' => 'object',
'default' => array(),
'editor_script' => 'acme-field-price',
'storage' => array(
'type' => 'object',
'rest_schema' => array(
'type' => 'object',
'properties' => array(
'amount' => array( 'type' => 'number', 'minimum' => 0 ),
'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
),
'additionalProperties' => false,
),
),
) );
} );
attribute é o tipo do atributo WordPress, neste caso object. storage.type é
o tipo de valor usado quando o campo é armazenado nos metadados do post ou nas opções, e
storage.rest_schema é o esquema que WordPress valida nas gravações de REST.
Sem um rest_schema, um valor de objeto recebe um esquema permissivo que aceita
quaisquer propriedades.
Registre em init com a prioridade padrão. Blockstudio detecta blocos tardiamente
em init, e um tipo que não estiver registrado até então fica de fora dos
atributos de bloco gerados.
bs_register_field_type() retorna true em caso de sucesso e false quando o nome
ou a definição são inválidos. Os nomes devem estar em minúsculas, usar namespace e seguir o padrão dashcase;
dois namespaces são reservados:
| Nome | Resultado |
|---|---|
acme/price |
true |
Acme/Price |
false, não está em minúsculas |
custom/price |
false, reservado para grupos de campos reutilizáveis |
blockstudio/price |
false, reservado para o núcleo Blockstudio |
bs_unregister_field_type() remove novamente um registro, e o
filtro blockstudio/field_types aceita as mesmas definições em um array indexado
pelo nome.
Criar o controle do editor
O script registrado acima fornece o componente React. Ele usa os componentes WordPress já carregados no editor, portanto não requer uma etapa de compilação:
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/price', {
component(props) {
const value =
props.value && typeof props.value === 'object' && !Array.isArray(props.value)
? props.value
: {};
const currencies = props.currencies || ['EUR'];
return el(
Flex,
{ align: 'flex-end' },
el(
FlexBlock,
{},
el(TextControl, {
label: props.label,
type: 'number',
min: 0,
step: 0.01,
disabled: props.disabled,
value: value.amount ?? '',
onChange(next) {
props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
},
}),
),
el(
FlexItem,
{},
el(SelectControl, {
label: 'Currency',
hideLabelFromVision: true,
disabled: props.disabled,
value: value.currency || currencies[0],
options: currencies.map((code) => ({ label: code, value: code })),
onChange(next) {
props.onChange({ ...value, currency: next });
},
}),
),
);
},
});
O componente recebe todas as propriedades da definição do campo, então a
chave currencies que você colocou em block.json chega como props.currencies. Ele também
recebe propriedades estáveis: value, onChange, field, defaultValue,
attributes, block, clientId, disabled e inRepeater com
repeaterId ao renderizar dentro de uma linha do repetidor. onChange armazena o valor
exatamente como recebido. Valores personalizados ignoram a normalização de opções aplicada pelos campos nativos
select, radio, color e gradient.
Proteja-se contra valores que não sejam objetos, como fazem as primeiras linhas. Um bloco salvo antes de o campo existir, ou com outro formato, ainda deve abrir no editor.
Blockstudio enfileira acme-field-price no editor de blocos somente quando um bloco
que usa acme/price está registrado. Se o script não conseguir registrar o
controle, o editor mantém o valor salvo e exibe um aviso não editável
no lugar do campo, e o site ainda renderiza o valor.
Usar em um bloco
Um bloco de preços usa o tipo duas vezes: uma para o preço inicial, que deve ser consultável fora do bloco, e outra para cada linha de um repetidor de níveis:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/pricing",
"title": "Pricing",
"blockstudio": {
"attributes": [
{
"id": "price",
"type": "acme/price",
"label": "Starting price",
"currencies": ["EUR", "USD"],
"default": { "amount": 19, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_price"
}
},
{
"id": "tiers",
"type": "repeater",
"label": "Tiers",
"min": 0,
"max": 4,
"attributes": [
{ "id": "name", "type": "text", "label": "Name", "default": "" },
{
"id": "price",
"type": "acme/price",
"label": "Price",
"currencies": ["EUR", "USD"],
"default": { "amount": 0, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_tier_prices"
}
}
]
}
]
}
}
Uma definição no nível do campo default prevalece sobre o padrão do registro. Blockstudio transforma ambos
os campos em atributos WordPress definidos pelo registro. O tipo de bloco registrado contém:
{
"price": {
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 19, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_price" }
},
"tiers": {
"blockstudio": true,
"type": "array",
"field": "repeater",
"id": "tiers",
"attributes": [
{ "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
{
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 0, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
}
]
}
}
Renderizar o valor
No modelo, o valor é um array comum. Verifique seu formato antes de usá-lo, pois um valor armazenado só é confiável até a última gravação:
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
if ( ! is_array( $price ) ) {
return '';
}
$amount = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';
return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
<p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
<?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
<div class="acme-tier">
<h3><?php echo esc_html( $tier['name'] ); ?></h3>
<p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
</div>
<?php endforeach; ?>
</section>
O ?: array() é importante. Um repetidor sem linhas chega ao modelo como
false, não como um array vazio, e um foreach direto sobre ele gera um aviso de PHP.
A linha @var é explicada abaixo, em análise estática.
Renderizando o bloco com um preço inicial e dois níveis:
echo bs_block( array(
'name' => 'acme/pricing',
'data' => array(
'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
'tiers' => array(
array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
),
),
) );
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
<p>From 19.00 EUR</p>
<div class="acme-tier">
<h3>Starter</h3>
<p>19.00 EUR</p>
</div>
<div class="acme-tier">
<h3>Team</h3>
<p>49.00 EUR</p>
</div>
</section>
Sem dados, o valor padrão do campo é aplicado e o bloco é renderizado
From 19.00 EUR sem níveis. Twig e Blade leem o mesmo valor que
a.price.amount e $a['price']['amount'], e os modelos da extensão podem acessá-lo como
{attributes.price.amount}.
Armazenamento e esquema REST
Ambos os campos declaram armazenamento postMeta, então Blockstudio registra duas chaves de metadados
quando compila o bloco. O campo de nível superior usa o esquema de armazenamento registrado
como está:
{
"type": "object",
"single": true,
"show_in_rest": {
"schema": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
O campo dentro do repetidor armazena um valor por linha, então sua chave de metadados usa um array, e o mesmo esquema se torna o esquema dos itens:
{
"type": "array",
"single": true,
"show_in_rest": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
}
Salvar um post que contém o bloco sincroniza ambas as chaves. Com os dois níveis acima,
get_post_meta( $id, 'acme_price', true ) retorna
{"amount":19,"currency":"EUR"} e acme_tier_prices retorna a lista de
preços das linhas:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Ambas as chaves aparecem na resposta REST do post sob meta, e as gravações de REST são
validadas pelo esquema. Uma gravação com moeda em minúsculas é rejeitada:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Os metadados são uma cópia. Os atributos do bloco no conteúdo do post continuam sendo a fonte,
e cada salvamento volta a sincronizá-los com as chaves configuradas; assim, um valor gravado
diretamente nos metadados é substituído na próxima vez que o post for salvo. O armazenamento de opções funciona
da mesma forma por meio de register_setting(). Tipos de campos personalizados, incluindo
armazenamento em array dentro de repetidores, estão disponíveis desde Blockstudio 7.5.0.
Análise estática
A extensão PHPStan conhece os tipos de campo integrados, mas não
os que um projeto registra em tempo de execução. Em um bloco que usa acme/price,
ela informa que o tipo de campo é desconhecido e tipa seu valor como mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ignore esse diagnóstico para seus próprios tipos na configuração do projeto,
e mantenha a verificação de formato no modelo; é isso que PHPStan precisa para aceitar o
valor mixed no nível max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Com essa configuração e o modelo acima, a análise é aprovada. Na versão 7.6,
o modelo também precisa da linha @var, com mixed nas posições dos campos personalizados; na versão
7.7, Blockstudio infere esse formato sozinho e a linha pode ser removida. Consulte Modelos verificados com PHPStan para
executar a análise.
Próximas etapas
- Tipos de campos personalizados: todas as chaves de definição, o filtro API e a lista completa de propriedades do componente.
- Armazenamento: armazenamento nos metadados do post e nas opções para qualquer campo.
- Guia de padrões de campos: grupos, repetidores e estruturas reutilizáveis de campos.
- Campos personalizados: grupos de campos reutilizáveis por meio de
custom/{name}.