Pular para o conteúdo

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-name usa 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:

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

Text
namespace/type-name

Exemplos válidos:

  • acme/dimensions
  • acme/text-options
  • theme/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:

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:

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

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

Registro de JavaScript

O script do editor registra o controle React correspondente:

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() retorna true quando o registro é aceito. Remova um registro no cliente com:

JavaScript
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

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>

Caminhos para objetos aninhados também funcionam em modelos de extensão:

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

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