Migração de ACF Blocks
Se você cria blocos personalizados de WordPress com ACF (Advanced Custom Fields), migrar para Blockstudio é simples. Os conceitos são parecidos: você define campos, escreve um template e o bloco aparece no editor. As diferenças são que Blockstudio detecta as pastas de blocos automaticamente, declara campos no próprio esquema dentro de block.json e fornece a cada template os valores dos campos em um único array $a.
Este guia apresenta a migração passo a passo, com comparações lado a lado dos padrões de ACF e Blockstudio.
A principal diferença
Desde ACF 6.0, um bloco ACF é um block.json com uma chave acf que identifica seu template de renderização, e cada pasta de bloco é registrada com sua própria chamada register_block_type(). Os campos vêm de um grupo de campos associado ao bloco por uma regra de localização de bloco (criado no painel de administração, sincronizado por meio de Local JSON ou registrado com acf_add_local_field_group()) ou, desde ACF PRO 6.8.1, de um array acf.fields em linha no mesmo block.json. Blockstudio substitui a chamada de registro pela descoberta automática baseada em arquivos: crie uma pasta com um block.json e um index.php, e o bloco será registrado automaticamente.
ACF:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
acf_add_local_field_group([
'key' => 'group_hero',
'title' => 'Hero Fields',
'fields' => [
['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
],
'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
<h1><?php echo esc_html($title); ?></h1>
</div>
Blockstudio:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
<h1><?php echo esc_html($a['title']); ?></h1>
</div>
Não é preciso chamar um registro nem criar um callback de renderização: a estrutura de pastas faz o registro, e os campos ficam em block.json ao lado do template. O template lê $a em vez de chamar get_field().
Registro de blocos
ACF
Os blocos ACF atuais são registrados a partir de um block.json com uma chave acf (renderTemplate ou renderCallback, além de opções como blockVersion), carregado por uma chamada explícita a register_block_type() para cada pasta de bloco, normalmente em init dentro de functions.php ou em um arquivo de plugin. Blocos mais antigos ainda podem usar acf_register_block_type(), que ACF documenta como obsoleto desde ACF 6.0; ele continua funcionando, então migre esses blocos da mesma forma.
Blockstudio
Crie uma pasta no diretório blockstudio/ do seu tema (ou em blocks/, se preferir). Adicione um block.json com os metadados de bloco padrão WordPress e uma chave blockstudio. Pronto.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json usa o formato padrão WordPress block.json, com a chave blockstudio para campos e configurações:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Acessar valores dos campos
Esta é a mudança mais comum que você fará durante a migração.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (sempre disponível) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
A variável $a é um atalho para $attributes e contém todos os valores dos campos do bloco atual. Ela está sempre disponível no template, tanto no editor quanto no frontend.
Variáveis de template
Blockstudio fornece várias variáveis em cada template:
| Variável | Atalho | Descrição |
|---|---|---|
$attributes |
$a |
Todos os valores dos campos |
$block |
$b |
Metadados do bloco (name, title, dir, url, postId) |
$context |
$c |
Contexto do bloco pai |
$content |
Conteúdo de InnerBlocks | |
$post_id |
ID do post atual (funciona no editor e no frontend; post_id ou postId em Twig) |
Mapeamento de tipos de campo
A maioria dos tipos de campo ACF tem equivalentes diretos em Blockstudio. A sintaxe JSON é diferente, mas os conceitos correspondem bem.
Campos de texto e conteúdo
ACF:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }
Para texto editável no editor de blocos (não apenas uma entrada de texto), use o tipo richtext com o componente <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Campos de imagem e arquivo
Os campos ACF image e file correspondem ao tipo files de Blockstudio:
ACF:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }
A estrutura do objeto retornado é semelhante:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Propriedades disponíveis: ID, title, alt, caption, description, href, url, sizes. As dimensões ficam em sizes, por exemplo $a['photo']['sizes']['full-width'].
Seleção, rádio e caixa de seleção
ACF:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"id": "color",
"type": "select",
"label": "Color",
"options": [
{ "value": "red", "label": "Red" },
{ "value": "blue", "label": "Blue" }
]
}
Use "returnFormat": "both" para obter o valor e o rótulo:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
O mesmo padrão se aplica aos tipos radio e checkbox.
Alternância e verdadeiro/falso
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Campo de link
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
Cor e gradiente
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
O tipo color se integra à paleta de cores WordPress. O tipo gradient oferece um seletor de gradiente.
Número, intervalo e data
ACF:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }
Repetidores
O campo repetidor de ACF corresponde diretamente ao tipo repeater de Blockstudio. Os templates ACF normalmente percorrem os dados com have_rows() / the_row() / get_sub_field() (get_field() em um repetidor também retorna um array de linhas); Blockstudio tem apenas o array PHP simples, já em $a.
ACF:
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
['name' => 'title', 'type' => 'text'],
['name' => 'description', 'type' => 'textarea'],
]]
// Template
if (have_rows('features')) :
while (have_rows('features')) : the_row();
echo get_sub_field('title');
echo get_sub_field('description');
endwhile;
endif;
Blockstudio:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?php foreach ($a['features'] as $feature) : ?>
<h3><?php echo esc_html($feature['title']); ?></h3>
<p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>
Os repetidores Blockstudio permitem aninhamento (um repetidor dentro de outro) até 3 níveis.
Grupos
O campo de grupo de ACF corresponde ao tipo group de Blockstudio. Os IDs dos campos dentro dos grupos recebem o prefixo do ID do grupo.
ACF:
['name' => 'author', 'type' => 'group', 'sub_fields' => [
['name' => 'name', 'type' => 'text'],
['name' => 'role', 'type' => 'text'],
]]
// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];
Blockstudio:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>
O helper bs_get_group() remove o prefixo do grupo dos IDs dos campos, permitindo acessá-los diretamente. Sem ele, você acessaria os campos como $a['author_name'] e $a['author_role'].
Lógica condicional
Tanto ACF quanto Blockstudio permitem lógica condicional para mostrar e ocultar campos com base nos valores de outros campos.
ACF:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
"id": "subtitle",
"type": "text",
"label": "Subtitle",
"conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}
As condições de Blockstudio referenciam IDs de campos diretamente (não as chaves dos campos). Operadores disponíveis: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Blockstudio também permite condições globais baseadas no tipo de post, ID do post, função do usuário e ID do usuário:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Tanto ACF quanto Blockstudio permitem usar InnerBlocks para aninhar outros blocos no seu bloco personalizado, com a mesma tag <InnerBlocks /> e os mesmos atributos allowedBlocks, template e templateLock; por isso, esta parte do template geralmente pode ser mantida sem alterações.
Blockstudio:
<div useBlockProps class="my-wrapper">
<InnerBlocks
allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
template='<?php echo esc_attr(wp_json_encode([
["core/heading", ["placeholder" => "Section title"]],
["core/paragraph", ["placeholder" => "Section content"]]
])); ?>'
templateLock="insert"
/>
</div>
A tag <InnerBlocks /> é substituída pelo componente React no editor e pelo conteúdo renderizado do bloco no frontend.
Armazenamento de metadados do post
Tanto ACF Blocks quanto Blockstudio armazenam valores de campos como atributos de bloco no conteúdo do post por padrão, não em metadados do post. Isso significa que os valores dos campos não podem ser consultados com WP_Query, a menos que você opte pelo armazenamento em metadados.
ACF adicionou o armazenamento opcional de metadados do post para blocos em ACF PRO 6.3 por meio de usePostMeta: true, para um bloco de nível superior por página. Blockstudio tem um mecanismo opcional por campo, usando a propriedade storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
A chave de metadados é registrada automaticamente com show_in_rest. Acesse-a em qualquer lugar com get_post_meta($post_id, 'is_featured', true).
Para valores de todo o site (como páginas de opções ACF), use o armazenamento de opções:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Estendendo blocos existentes
A regra de localização de blocos de ACF associa grupos de campos apenas a blocos ACF; ela não adiciona campos a blocos do núcleo ou de terceiros. O caminho de ACF para blocos do núcleo, como Título, Parágrafo, Imagem e Botão, é WordPress Block Bindings API, que conecta atributos de blocos existentes a valores de campos de ACF. Blockstudio pode adicionar novos campos e controles a qualquer bloco registrado por meio de arquivos de extensão.
Crie um arquivo de extensão no diretório blockstudio:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
A propriedade set aplica automaticamente o valor do campo ao HTML do bloco. Use curingas para estender vários blocos de uma só vez: "name": "core/*".
Lista de verificação da migração
- Crie a pasta do bloco em
theme/blockstudio/{block-name}/comblock.jsoneindex.php. - Mova as definições de campos do grupo de campos do bloco (Local JSON,
acf_add_local_field_group()ou uma matrizacf.fieldsinline) para a matrizblockstudio.attributesemblock.json. Alterenameparaid, removakeye ajuste os nomes dos tipos conforme necessário. - Atualize o acesso ao modelo de
get_field('name')para$a['name']. Substitua os loopshave_rows()porforeach ($a['repeater'] as $item). - Substitua
get_sub_field()pelo acesso direto à matriz:$item['fieldId']. - Adicione
useBlockPropsao elemento mais externo do modelo para integrar corretamente com o editor. - Mova a lógica condicional de
conditional_logicde ACF paraconditionsde Blockstudio, usando os IDs dos campos em vez das chaves. - Adicione armazenamento para quaisquer campos que antes eram consultados por meio de
get_post_meta()ou usados emWP_Query. - Remova o código de registro de ACF: as chamadas
register_block_type()e as chavesacfdos blocos migrados (ou suas chamadasacf_register_block_type()) e seus grupos de campos, estejam eles em Local JSON,acf_add_local_field_group(), uma matrizacf.fieldsinline ou no painel de administração. - Teste no editor para verificar se os campos aparecem corretamente e, em seguida, confira a saída do site.