Pular para o conteúdo

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:

PHP
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:

JavaScript
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:

JSON
{
  "$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:

JSON
{
  "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
<?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:

PHP
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' ) ),
		),
	),
) );
HTML
<!--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á:

JSON
{
  "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:

JSON
{
  "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:

JSON
[
  { "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:

JSON
{
  "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:

Text
  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:

Neon
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