Crear un tipo de campo personalizado
Algunos valores constan de más de un dato primitivo. Un precio incluye una cantidad y una moneda. Con los campos integrados, se representa como un campo numérico junto a un campo de selección, y cada bloque que muestra un precio repite el par, las etiquetas y la lógica que los mantiene unidos. En los metadatos de la entrada se convierte en dos claves y, dentro de un repetidor, en dos listas paralelas.
Un tipo de campo personalizado convierte el par en un solo campo. Registre una vez un tipo como acme/price en PHP y en JavaScript, y luego úselo en cualquier block.json como un campo nativo: en el nivel superior, dentro de grupos y repetidores, con almacenamiento en los metadatos de la entrada o en opciones, y en plantillas PHP, Twig y Blade. Blockstudio obtiene el atributo WordPress y el esquema de almacenamiento REST a partir del registro.
Esto es distinto de un campo personalizado.
Una referencia custom/{name} reutiliza un grupo de campos existentes. Un tipo de campo personalizado añade un control nuevo con su propia estructura de valor.
Esta guía crea acme/price de principio a fin: el registro PHP, el control del editor, un bloque de precios que lo utiliza en el nivel superior y dentro de un repetidor, el almacenamiento en metadatos de la entrada con un esquema REST estricto y el resultado renderizado.
Registrar el tipo en PHP
La parte PHP declara el tipo de atributo, el valor predeterminado, el script del editor que proporciona el control y cómo se almacena el valor fuera del bloque:
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 es el tipo de atributo WordPress, en este caso object. storage.type es el tipo de valor que se usa cuando el campo se almacena en los metadatos de la entrada o en las opciones, y storage.rest_schema es el esquema WordPress con el que se validan las escrituras de REST.
Sin un rest_schema, un valor de objeto obtiene un esquema permisivo que acepta cualquier propiedad.
Regístrelo en init con la prioridad predeterminada. Blockstudio detecta los bloques tarde en init, y cualquier tipo que no esté registrado para entonces queda fuera de los atributos de bloque generados.
bs_register_field_type() devuelve true si tiene éxito y false si el nombre o la definición no son válidos. Los nombres deben estar en minúsculas, incluir un espacio de nombres y usar guiones; hay dos espacios de nombres reservados:
| Nombre | Resultado |
|---|---|
acme/price |
true |
Acme/Price |
false, no está en minúsculas |
custom/price |
false, reservado para grupos de campos reutilizables |
blockstudio/price |
false, reservado para el núcleo de Blockstudio |
bs_unregister_field_type() elimina un registro y el filtro blockstudio/field_types acepta las mismas definiciones como un arreglo indexado por nombre.
Crear el control del editor
El script registrado arriba proporciona el componente React. Utiliza los componentes WordPress que ya están cargados en el editor, así que no necesita compilarse:
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 });
},
}),
),
);
},
});
El componente recibe todas las propiedades de la definición del campo, por lo que la clave currencies que incluya en block.json llega como props.currencies. También recibe propiedades estables: value, onChange, field, defaultValue, attributes, block, clientId, disabled y inRepeater con repeaterId cuando se renderiza dentro de una fila del repetidor. onChange almacena el valor exactamente tal como se proporciona. Los valores personalizados omiten la normalización de opciones que aplican los campos nativos select, radio, color y gradient.
Como muestran las primeras líneas, compruebe que los valores sean objetos. Un bloque guardado antes de que existiera el campo, o con una estructura distinta, debería poder abrirse igualmente en el editor.
Blockstudio carga acme-field-price en el editor de bloques solo cuando hay un bloque registrado que utiliza acme/price. Si el script no registra el control, el editor conserva el valor guardado y muestra un aviso no editable en lugar del campo; la interfaz pública sigue mostrando el valor.
Usarlo en un bloque
Un bloque de precios usa el tipo dos veces: una para un precio inicial que debe poder consultarse fuera del bloque y otra en cada fila de un repetidor de niveles:
{
"$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"
}
}
]
}
]
}
}
Un default de campo tiene prioridad sobre el valor predeterminado del registro. Blockstudio convierte ambos campos en atributos WordPress del registro. El tipo de bloque registrado contiene:
{
"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 el valor
En la plantilla, el valor es un arreglo normal. Verifique su estructura antes de usarlo, porque un valor almacenado solo es tan fiable como lo último que lo escribió:
<?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>
?: array() es importante. Un repetidor sin filas llega a la plantilla como false, no como un arreglo vacío, y un foreach sin más sobre él genera una advertencia PHP. La línea @var se explica más abajo en Análisis estático.
Renderizar el bloque con un precio inicial y dos niveles:
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>
Si no hay ningún dato, se aplica el valor predeterminado del campo y el bloque se renderiza como From 19.00 EUR sin niveles. Twig y Blade leen el mismo valor que a.price.amount y $a['price']['amount'], y las plantillas de extensión pueden acceder a él como {attributes.price.amount}.
Almacenamiento y esquema REST
Ambos campos declaran almacenamiento postMeta, así que Blockstudio registra dos claves meta al crear el bloque. El campo de nivel superior usa tal cual el esquema de almacenamiento registrado:
{
"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
}
}
}
El campo dentro del repetidor almacena un valor por fila, por lo que su clave meta se basa en un arreglo y el mismo esquema pasa a ser el esquema de elementos:
{
"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
}
}
}
}
Al guardar una entrada que contiene el bloque, se sincronizan ambas claves. Con los dos niveles anteriores, get_post_meta( $id, 'acme_price', true ) devuelve {"amount":19,"currency":"EUR"} y acme_tier_prices devuelve la lista de precios por fila:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Ambas claves aparecen en la respuesta REST de la entrada, bajo meta, y las escrituras REST se validan con el esquema. Se rechaza una escritura con la moneda en minúsculas:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Los metadatos son una copia. Los atributos de bloque del contenido de la entrada siguen siendo la fuente y cada guardado vuelve a sincronizarlos con las claves configuradas, por lo que un valor escrito directamente en los metadatos se reemplaza la próxima vez que se guarda la entrada. El almacenamiento en opciones funciona igual mediante register_setting(). Los tipos de campo personalizados, incluido el almacenamiento basado en arreglos dentro de repetidores, están disponibles desde Blockstudio 7.5.0.
Análisis estático
La extensión PHPStan conoce los tipos de campo integrados, pero no los que un proyecto registra durante la ejecución. En un bloque que utiliza acme/price, informa que el tipo de campo es desconocido y tipa su valor como mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Ignore ese diagnóstico para sus tipos propios en la configuración del proyecto y mantenga la comprobación de estructura en la plantilla; esto es lo que PHPStan necesita para aceptar el valor mixed en el nivel max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Con esa configuración y la plantilla anterior, el análisis se completa sin errores. En 7.6, la plantilla también necesita la línea @var, con mixed en las posiciones de los campos personalizados; Blockstudio 7.7 deduce esa estructura por sí solo y se puede quitar la línea. Consulte Plantillas verificadas con PHPStan para ejecutar el análisis.
Pasos siguientes
- Tipos de campos personalizados: todas las claves de definición, el filtro API y la lista completa de propiedades del componente.
- Almacenamiento: almacenamiento en los metadatos de la entrada y en opciones para cualquier campo.
- Guía de patrones de campos: grupos, repetidores y estructuras de campos reutilizables.
- Campos personalizados: grupos de campos reutilizables mediante
custom/{name}.