Campos personalizados
Los campos personalizados permiten definir grupos de campos reutilizables que pueden usarse en varios bloques. Son como plantillas de campos: se definen una vez y se usan en todas partes.
Los campos personalizados no son lo mismo que los tipos de campos personalizados. Usa custom/{name} para grupos reutilizables de campos existentes. Usa un tipo de campo personalizado con espacio de nombres, como acme/dimensions, cuando un tema o complemento registre un nuevo control de editor y una estructura de valores.
Registro del sistema de archivos
Crea un archivo field.json dentro de un directorio fields/ en el directorio blockstudio:
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.json
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "hero",
"title": "Hero Section",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "enabled", "type": "toggle", "label": "Enabled" }
]
}
Registro mediante el filtro PHP
Registra campos personalizados mediante programación con el filtro blockstudio/fields:
add_filter('blockstudio/fields', function ($fields) {
$fields['cta'] = [
'title' => 'Call to Action',
'attributes' => [
['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
['id' => 'url', 'type' => 'text', 'label' => 'URL'],
],
];
return $fields;
});
Uso en block.json
Haz referencia a un campo personalizado usando el tipo custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Esto expande en línea los campos definidos en la definición del campo personalizado. Los campos expandidos conservan sus ID originales (heading, description, enabled).
Los campos personalizados también pueden reutilizar definiciones de grupos completas:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
Los campos secundarios del grupo se almacenan como section-header_kicker, section-header_title y así sucesivamente. En las plantillas, usa bs_get_group() para extraerlos en un objeto de grupo ordenado.
Estructura de ID
Usa idStructure para anteponer un prefijo o transformar los ID de campo. El marcador {id} se sustituye por el ID del campo original:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Esto genera campos con los ID: hero_heading, hero_description, hero_enabled.
Anulaciones
Personaliza campos individuales por instancia con overrides. Las claves son los ID de campo originales de la definición:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Las propiedades de reemplazo se combinan con la definición original del campo. Un reemplazo de id omite el patrón idStructure. En el ejemplo anterior, enabled pasa a ser active en lugar de hero_enabled.
La combinación se realiza en un solo nivel: una propiedad que se sobrescribe reemplaza por completo la propiedad original. Una sobrescritura de options es la lista completa de opciones, no una adición a ella; lo mismo ocurre con conditions y con attributes de un grupo. Después se añaden las condiciones de la referencia.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Este bloque solo ofrece blanco y gris, por muchas opciones que incluya la definición.
Condiciones
Las condiciones de las definiciones de campos personalizados se reescriben automáticamente cuando se aplica idStructure. Un campo cuya condición depende de un campo hermano sigue funcionando tras la expansión.
{
"name": "font-size",
"attributes": [
{ "id": "enable", "type": "toggle", "label": "Modify font size" },
{
"id": "min",
"type": "number",
"label": "Min Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
},
{
"id": "max",
"type": "number",
"label": "Max Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio lo expande a title_font_enable, title_font_min, title_font_max y reescribe las condiciones para que hagan referencia a title_font_enable en lugar de enable. Los conmutadores funcionan exactamente igual que si los campos se hubieran definido en línea.
Condiciones a nivel de referencia
Añade conditions a la referencia para aplicarlas a todos los campos expandidos. Esto resulta útil para ocultar un grupo entero tras un conmutador externo:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Estas condiciones se combinan con las ya definidas dentro de la definición del campo. Los ID de las condiciones también se reescriben mediante idStructure.
Varios campos personalizados
Puedes usar varios campos personalizados en un mismo bloque, junto con campos normales:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Anidamiento
Los campos personalizados funcionan dentro de grupos, pestañas y repetidores:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Rutas de detección adicionales
Usa el filtro blockstudio/fields/paths para añadir directorios adicionales donde detectar campos:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Análisis estático
El paquete blockstudio/phpstan expande las referencias custom/* basadas en archivos al validar PHP, Twig, Blade, las etiquetas de bloque y las estructuras de atributos inferidas. Su expansión sigue las mismas reglas de anidamiento, idStructure y overrides descritas anteriormente.
Para las definiciones fuera del proyecto analizado, añade el directorio de la biblioteca a blockstudioScanRoots en phpstan.neon. Los campos registrados únicamente mediante el filtro blockstudio/fields PHP existen en tiempo de ejecución y no se pueden inferir estáticamente.