Saltar al contenido

Tipos de campos personalizados

Los tipos de campos personalizados permiten que un tema o complemento añada nuevos controles de campo Blockstudio. Son distintos de los campos personalizados:

  • custom/{name} hace referencia a un grupo reutilizable de campos existentes.
  • namespace/type-name usa un tipo de campo registrado con su propio control del editor y su estructura de valores.

Blockstudio proporciona el sistema de registro. El tema o complemento proporciona el control.

Cuándo usarlos

Usa un tipo de campo personalizado cuando un proyecto necesite un control de edición específico que deba comportarse como un campo Blockstudio nativo en todas partes:

  • atributos de bloque
  • grupos de campos custom/{name} reutilizables
  • grupos, pestañas y repetidores
  • plantillas PHP, Twig y Blade
  • metadatos de contenido y almacenamiento de opciones
  • plantillas de extensión como {attributes.margin.top}

Por ejemplo, un control de espaciado puede almacenar un objeto en lugar de cuatro campos de texto independientes:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Nombres

Los nombres de los tipos de campo personalizados deben estar en minúsculas, tener un espacio de nombres y usar el formato dashcase:

Text
namespace/type-name

Ejemplos válidos:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Espacios de nombres reservados:

  • custom/ está reservado para grupos de campos personalizados reutilizables.
  • blockstudio/ está reservado para el núcleo de Blockstudio.

El filtro API ignora los nombres no válidos y el ayudante API los rechaza.

Registro de PHP

Registra los metadatos del tipo de campo en 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() devuelve true cuando el registro se realiza correctamente y false cuando el nombre o la definición no son válidos. Puedes anular un registro manual con bs_unregister_field_type().

También puedes usar el 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;
});

Claves de definición

Clave Tipo Descripción
attribute string, array, null Tipo de atributo WordPress. Use string, number, boolean, object, array o una matriz de esos tipos.
default mixed Valor predeterminado del registro cuando un campo no define el suyo.
source string Origen del atributo WordPress para casos de serialización personalizados.
produces_attribute boolean Establézcalo en false para controles solo de visualización. El valor predeterminado es true.
editor_script string or array Identificador o identificadores de script registrados que se cargarán en el editor de bloques cuando se use el tipo.
editor_style string or array Identificador o identificadores de estilo registrados que se cargarán en el editor de bloques cuando se use el tipo.
storage array Tipo de valor de almacenamiento e indicaciones de esquema REST para los metadatos de entradas y las opciones.
supports array Indicadores de capacidad opcionales para su propio control.
translate boolean Establézcalo en true cuando el valor sea texto para que WPML lo traduzca. Requiere attribute string.

Una definición con un valor translate que no sea booleano, o con translate establecido en true y un attribute distinto de string, no es válida. bs_register_field_type() devuelve false y el filtro API la ignora.

WPML

wp bs wpml config no puede determinar solo a partir del registro si el valor de un tipo de campo personalizado es texto, por lo que omite esos campos y muestra una advertencia para cada uno. Establezca translate en true en el registro de un tipo de campo que almacene una cadena de texto sin formato; entonces el comando declara sus campos como los campos text. Un campo puede seguir excluyéndose con "translate": false. Consulte WPMLreferencias portátiles a medios.

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

Registro de JavaScript

El script del editor registra el control React correspondiente:

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() devuelve true cuando se acepta el registro. Elimina un registro del cliente con:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

El componente recibe las propiedades de definición del campo y estas propiedades estables:

Propiedad Descripción
type Nombre del tipo de campo.
id ID del campo.
field Definición completa del campo de block.json.
value Valor guardado actual.
defaultValue Valor predeterminado del campo.
onChange Guarda directamente un valor nuevo.
attributes Atributos del bloque actual.
block Definición del tipo de bloque actual.
clientId ID de cliente del bloque actual en el editor.
inRepeater Indica si el campo está dentro de una fila de repetidor.
repeaterId Ruta del repetidor actual, si la hay.
disabled Indica si el campo está desactivado en el editor.

Los valores de los tipos de campo personalizados se almacenan directamente. No pasan por la normalización de opciones nativas de select, radio, color o gradient.

Representación de valores

Los valores de objeto están disponibles como cualquier otro 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>

Las rutas de objetos anidados también funcionan en las plantillas de extensión:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Almacenamiento

Cuando se usa un tipo de campo personalizado con el almacenamiento postMeta o option, Blockstudio usa el tipo de valor de almacenamiento registrado y el esquema REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

Para los valores array y object, define storage.rest_schema en el registro del tipo de campo. Los elementos descendientes del repetidor siguen usando almacenamiento basado en arrays, ya que un repetidor almacena filas.

Comportamiento alternativo

Si PHP conoce el tipo de campo, pero el script del editor no registra un control correspondiente, Blockstudio conserva el valor guardado y muestra un aviso no editable en el editor. La representación en el frontend sigue recibiendo el valor guardado.

Si un tipo de campo no está registrado en PHP, Blockstudio lo excluye de los atributos WordPress generados. Registra la definición PHP antes de que se ejecute la detección de bloques, normalmente en init antes de que Blockstudio genere los bloques.