Saltar al contenido

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:

Código
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
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:

PHP
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}:

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

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "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:

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

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

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

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

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

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

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

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