Campos personalizados
Os campos personalizados permitem definir grupos de campos reutilizáveis que podem ser referenciados em vários blocos. Pense neles como modelos de campos: defina uma vez e use em todos os lugares.
Campos personalizados não são o mesmo que
tipos de campos personalizados. Use
custom/{name} para grupos reutilizáveis de campos existentes. Use um tipo de campo personalizado com namespace, como acme/dimensions, quando um tema ou plugin registrar um novo controle de editor e formato de valor.
Registro no sistema de arquivos
Crie um arquivo field.json dentro de um diretório fields/ no diretório 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 pelo filtro PHP
Registre campos personalizados programaticamente usando o 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 em block.json
Faça referência a um campo personalizado usando o tipo custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Isso expande os campos definidos na definição do campo personalizado diretamente no local. Os campos expandidos usam seus IDs originais (heading, description, enabled).
Campos personalizados também podem reutilizar definições de grupo 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" }]
}
}
Os campos filhos do grupo são armazenados como section-header_kicker,
section-header_title e assim por diante. Nos modelos, use bs_get_group() para
extraí-los em um objeto de grupo organizado.
Estrutura de IDs
Use idStructure para prefixar ou transformar IDs de campos. O marcador {id} é substituído pelo ID original do campo:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Isso gera campos com os IDs: hero_heading, hero_description, hero_enabled.
Substituições
Personalize campos individuais por instância usando overrides. As chaves são os IDs originais dos campos na definição:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
As propriedades substituídas são mescladas à definição original do campo. Uma substituição de id ignora o padrão idStructure. No exemplo acima, enabled passa a ser active em vez de hero_enabled.
A mesclagem tem apenas um nível: uma propriedade que você substitui substitui a propriedade original por completo. Uma substituição de options corresponde à lista completa de opções, não a um acréscimo a ela, e o mesmo vale para conditions e para o attributes de um grupo. As condições da referência ainda são adicionadas depois.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Este bloco oferece apenas Branco e Cinza, independentemente de quantas opções a definição listar.
Condições
As condições nas definições de campos personalizados são reescritas automaticamente quando idStructure é aplicado. Um campo que depende condicionalmente de um campo irmão continua funcionando após a expansão.
{
"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 expande isso para title_font_enable, title_font_min,
title_font_max e reescreve as condições para fazer referência a
title_font_enable em vez de enable. Os toggles de controle funcionam
exatamente como se os campos tivessem sido definidos diretamente.
Condições no nível da referência
Adicione conditions à referência para aplicá-las a cada campo expandido. Isso
é útil para ocultar um grupo inteiro com um toggle externo:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Essas condições são mescladas com as condições já definidas na definição do campo. Os IDs das condições também são reescritos por meio de idStructure.
Vários campos personalizados
Você pode usar vários campos personalizados em um único bloco, junto com campos comuns:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Aninhamento
Campos personalizados funcionam dentro de grupos, abas e repetidores:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Caminhos adicionais de descoberta
Use o filtro blockstudio/fields/paths para adicionar outros diretórios à descoberta de campos:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Análise estática
O pacote blockstudio/phpstan expande referências custom/* baseadas em arquivos ao validar PHP, Twig, Blade, tags de bloco e formatos de atributos inferidos. A expansão segue as mesmas regras de aninhamento, idStructure e overrides descritas acima.
Para definições fora do projeto analisado, adicione o diretório da biblioteca a blockstudioScanRoots em phpstan.neon. Campos registrados apenas pelo filtro blockstudio/fields PHP existem em tempo de execução e não podem ser inferidos estaticamente.