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-nameusa 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:
{
"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:
namespace/type-name
Ejemplos válidos:
acme/dimensionsacme/text-optionstheme/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:
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:
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.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Registro de JavaScript
El script del editor registra el control React correspondiente:
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:
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
<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>
Las rutas de objetos anidados también funcionan en las plantillas de extensión:
{
"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.
{
"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.