ACF PRO Gutenberg: corrigir incompatibilidade no editor

Tipo Page Builders

Nome do erro Incompatibilidade do ACF PRO com o Gutenberg EN: ACF PRO incompatible with Gutenberg editor

Severidade Atenção

Descrição A incompatibilidade do ACF PRO com o Gutenberg ocorre quando o plugin Gutenberg standalone, uma versão defasada do ACF ou um block.json mal registrado impedem que campos e ACF Blocks apareçam no editor de blocos.

O que é incompatibilidade do ACF PRO Gutenberg?

O ACF PRO integra dados ao editor Gutenberg de duas formas: grupos de campos (meta boxes) anexados a posts e páginas por regras de localizacao, e os ACF Blocks, blocos nativos registrados via block.json e renderizados pelo servidor. A incompatibilidade aparece quando essa integração deixa de funcionar: os campos somem do painel lateral do editor, ou um ACF Block exibe a mensagem de bloco quebrado e não renderiza o conteúdo.

A causa raiz mais comum, segundo a documentação oficial do ACF, e o uso do plugin Gutenberg standalone instalado a parte. Ele força versões experimentais e novas versões da Block API que o ACF ainda não suporta, derrubando a renderizacao dos ACF Blocks. Versões antigas do ACF (anteriores a 6.0, que introduziu o registro por block.json exigindo WordPress 5.8 ou superior) e erros de configuração do block.json completam o quadro.

Como identificar

Mensagem ‘This block has encountered an error and cannot be previewed’ ou ‘Your site doesn’t include support for this block’ aparece no lugar do ACF Block dentro do editor de blocos.
Os grupos de campos do ACF não aparecem mais na lateral nem abaixo do editor ao editar um post ou página no Gutenberg.
O ACF Block some da lista do inserter (botão + ‘Adicionar bloco’) mesmo com o campo registrado no código.
Aviso ‘Block validation’ ou ‘attempt to recover’ surge ao abrir um post que já continha um ACF Block.
No console do navegador aparecem erros de JavaScript da Block API logo ao carregar o editor com o ACF PRO ativo.

Antes de começar: Antes de editar o block.json ou alternar plugins e tema em producao, faça um backup do site (arquivos e banco de dados) ou teste primeiro em um ambiente de staging, para poder reverter caso a previa do editor quebre.

Como prevenir

Nunca instale o plugin Gutenberg standalone em producao: o editor de blocos já vem no nucleo do WordPress e o plugin força APIs experimentais incompativeis com o ACF.
Mantenha o ACF PRO e o WordPress sempre na versão estavel mais recente, validando antes em staging para acompanhar mudancas da Block API.
Padronize o registro de ACF Blocks por block.json com apiVersion 2 e render_template versionado no repositorio do tema ou plugin.
Documente as regras de localizacao dos grupos de campos para evitar que um ajuste de tipo de post esconda campos do editor sem querer.

Causa

O plugin Gutenberg standalone esta instalado e ativo: ele força versões experimentais da Block API que o ACF PRO ainda não suporta, quebrando a renderizacao dos ACF Blocks (causa número um na doc oficial do ACF).
A versão do ACF e anterior a 6.0, que introduziu o registro de blocos por block.json e exige WordPress 5.8 ou superior; em versões antigas o bloco não registra no editor atual.
O block.json do ACF Block esta com apiVersion incorreta (o ACF 6 usa apiVersion 2) ou com caminho de render_template apontando para um arquivo inexistente, o que impede o bloco de renderizar.
O grupo de campos esta com a opção Active desativada, ou a regra de localizacao não casa com o tipo de post sendo editado, fazendo os campos sumirem do editor de blocos.
Um conflito de JavaScript com outro plugin ou tema interrompe o carregamento da Block API antes do ACF inicializar seus campos e blocos no editor.

Como resolver

Desative o plugin Gutenberg standalone: Em Plugins, procure o plugin chamado apenas Gutenberg instalado a parte e desative-o. O editor de blocos já vem embutido no nucleo do WordPress, entao o plugin extra e desnecessario e e a causa número um de quebra dos ACF Blocks segundo a doc oficial.
```
Painel WP -> Plugins -> Plugins Instalados
Localize o plugin 'Gutenberg' (autor: Gutenberg Team) e clique em Desativar
```
Atualize o ACF PRO e o WordPress: Garanta o ACF PRO 6.0 ou superior, que introduziu o registro de blocos por block.json, e o WordPress 5.8 ou superior, exigido por esse registro. Versões anteriores não reconhecem o bloco no editor atual.
```
Painel WP -> Plugins -> verifique a versão do Advanced Custom Fields PRO (alvo: 6.0+)
Painel WP -> Painel -> Atualizações -> atualize o WordPress para 5.8+
```
Confira o registro do ACF Block no block.json: Abra o block.json do bloco e confirme a apiVersion suportada pelo ACF 6 e o caminho do render_template. Um caminho de template inexistente faz o bloco quebrar na previa do editor.
```
"apiVersion": 2
"acf": { "renderTemplate": "template-do-bloco.php" }
Confirme que o arquivo de render_template existe na pasta do bloco
```
Verifique o grupo de campos e a regra de localizacao: Em ACF -> Grupos de Campos, abra o grupo que sumiu e confirme que ele esta marcado como Active e que a regra de localizacao casa com o tipo de post que você esta editando. Regra errada esconde os campos do editor.
```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo
Marque o status como Active (Ativo)
Ajuste a regra de Localizacao para 'Tipo de Post e igual a' o post editado
```
Isole conflito de JavaScript no editor: Se os campos e blocos ainda falharem, desative os outros plugins um a um e troque para um tema padrão, recarregando o editor a cada teste para identificar o plugin ou tema que interrompe a Block API. Reative depois de achar o culpado.
```
Painel WP -> Plugins -> desative os demais plugins um a um
Painel WP -> Aparencia -> Temas -> ative um tema padrão (ex.: Twenty Twenty-Four)
Abra o console do navegador (F12 -> Console) e recarregue o editor a cada teste
```

PHP

<?php
add_action( 'init', 'full_register_acf_block' );
function full_register_acf_block() {
    if ( ! function_exists( 'acf_register_block_type' ) ) {
        return;
    }
    // Registro pelo block.json (recomendado no ACF 6) com apiVersion 2.
    register_block_type( __DIR__ . '/blocks/destaque' );
}

Perguntas frequentes

Por que meus campos do ACF PRO sumiram do editor Gutenberg

Na maioria dos casos o grupo de campos esta com o status Active desligado ou a regra de localizacao não casa com o tipo de post editado. Em ACF -> Grupos de Campos, reative o grupo e ajuste a localizacao para o post correto.

O plugin Gutenberg standalone quebra o ACF PRO

Sim. A documentação oficial do ACF afirma que o plugin Gutenberg instalado a parte força versões experimentais da Block API ainda não suportadas pelo ACF, derrubando a renderizacao dos ACF Blocks. Desative esse plugin, pois o editor de blocos já vem no nucleo.

Qual versão do ACF e do WordPress preciso para ACF Blocks no Gutenberg

O registro de blocos por block.json foi introduzido no ACF 6.0 e exige WordPress 5.8 ou superior. Use o ACF PRO 6.0 ou mais novo e mantenha o WordPress atualizado para o bloco ser reconhecido no editor.

Por que o ACF Block mostra 'This block has encountered an error'

Esse aviso costuma indicar um block.json com apiVersion incorreta ou um render_template apontando para um arquivo que não existe. Confirme a apiVersion 2 e o caminho do template, que precisa existir na pasta do bloco.

Preciso de JavaScript para renderizar um ACF Block

Não. Os ACF Blocks são dinâmicos e renderizados pelo servidor a cada carregamento por um render_template ou render_callback em PHP, sem exigir JavaScript do desenvolvedor, segundo a documentação do ACF.

Posso continuar usando acf_register_block_type em vez de block.json

Sim. Blocos registrados com acf_register_block_type continuam funcionando no ACF 6, mas o registro por block.json passou a ser o método recomendado. Migre quando puder para evitar problemas futuros de compatibilidade.

Como saber se o problema e do ACF ou de outro plugin

Desative os demais plugins um a um e troque para um tema padrão, recarregando o editor a cada teste. Se os campos e blocos voltarem, reative os itens até identificar o que interrompe a Block API.

Informativo

Como corrigir os estilos do WPForms que não aplicam com o Astra Pro no WordPress

Quando o estilo do WPForms não aplica com o Astra Pro, o formulário aparece sem CSS porque a opção Include Form Styling esta em No styling, o CSS do tema vence por especificidade, ou o cache combinou e removeu a folha de estilo do WPForms.

Atenção

Como corrigir estilos que não aplicam entre Ultimate Addons e Astra Pro no WordPress

O problema dos estilos do Ultimate Addons e Astra Pro que não aplicam acontece quando o CSS dos widgets UAEL fica preso em arquivos gerados desatualizados, em cache do site ou é sobrescrito pelo CSS dinâmico do Astra Pro, deixando o widget sem visual no frontend.

Atenção

Como corrigir o Event Calendar que não sincroniza no Essential Addons

O Event Calendar do Essential Addons não sincroniza quando a fonte de eventos escolhida no widget esta mal configurada: chave de API ou ID do Google Calendar incorretos, calendário do Google não público, ou o plugin The Events Calendar ausente quando ele e a fonte selecionada.

Atenção

Como corrigir o Google Maps Field no ACF PRO (chave de API)

O Google Maps Field do ACF PRO exige uma chave de API do Google registrada via filtro acf/fields/google_map/api ou acf_update_setting. Sem ela, o campo mostra um mapa cinza e o console acusa erro da Google Maps JavaScript API.

Grave

Como corrigir a incompatibilidade entre Astra Pro e Elementor Pro

O conflito entre Astra Pro e Elementor Pro acontece quando os dois constroem a mesma área da página ao mesmo tempo: o título aparece duplicado, o header e o rodape do Theme Builder se somam aos do Astra, ou a largura total não se aplica. A causa quase sempre e o Astra renderizar elementos que o Elementor Pro já monta.

Atenção

Como corrigir o erro de taxonomia no JetEngine

O erro de taxonomia no JetEngine acontece quando a taxonomia registrada na aba Taxonomies não aparece no menu, não fica disponível no post type vinculado ou retorna 404, geralmente por opções de visibilidade desligadas, slug invalido ou regras de reescrita não atualizadas.

Setores

Extensões

Integrações

Como corrigir a incompatibilidade do ACF PRO com o editor Gutenberg

O que é incompatibilidade do ACF PRO Gutenberg?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir os estilos do WPForms que não aplicam com o Astra Pro no WordPress

Como corrigir estilos que não aplicam entre Ultimate Addons e Astra Pro no WordPress

Como corrigir o Event Calendar que não sincroniza no Essential Addons

Como corrigir o Google Maps Field no ACF PRO (chave de API)

Como corrigir a incompatibilidade entre Astra Pro e Elementor Pro

Como corrigir o erro de taxonomia no JetEngine

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos