Um bloco WordPress block editor é uma unidade de conteúdo registrada no editor Gutenberg que aparece no menu “+” como qualquer parágrafo ou imagem. A diferença é que você define o comportamento, os campos editáveis e o HTML de saída. Isso resolve o problema de repetir a mesma estrutura (uma caixa de aviso, um card de produto, um CTA) em dezenas de posts. No suporte da FULL, a maioria dos tickets de Elementor que pedem “um componente reutilizável” se resolveria com um bloco nativo, mais leve. Este tutorial mostra o caminho completo, do scaffold ao registro, e quando vale mais usar o Elementor para iniciantes. Veja também todos os artigos de Elementor da FULL.

Primeiros passos: O que é um bloco WordPress block editor

Um bloco WordPress block editor tem 41,5% do mercado de sites a seu favor (W3Techs, 2026): ele usa a API oficial do Gutenberg e funciona em qualquer tema compatível, sem lock-in de builder. Na prática, é um par de arquivos: um block.json com os metadados e um index.js que define a edição e a saída no front-end.

O WordPress 6.x lê esse par e injeta o bloco no menu de inserção, ao lado de parágrafo e imagem.

A tabela abaixo separa os três tipos de componente que confundem quem começa. Cada um resolve um problema distinto, e escolher errado custa performance ou tempo de manutenção. Um block pattern é só um arranjo salvo de blocos existentes, sem código. Um bloco dinâmico renderiza via PHP a cada carregamento. Um widget Elementor vive fora do Gutenberg.

Por que criar um bloco nativo em vez de usar um page builder

Um bloco nativo carrega em média 200 KB a menos de CSS e JavaScript que uma seção equivalente montada em page builder, porque só enfileira o que a página usa. Esse é o ganho técnico central: o Gutenberg trabalha com assets por bloco, então o navegador baixa o CSS do seu card apenas onde o card aparece. Um page builder tende a carregar a biblioteca inteira no site todo.

A diferença aparece no Core Web Vitals. Em sites que chegam ao suporte da FULL com LCP acima de 4 segundos, boa parte do peso vem de bibliotecas de builder carregadas em páginas que nem usam o builder. Um bloco WordPress block editor evita isso por construção. Para comparar as duas abordagens em detalhe, o guia Elementor vs Gutenberg mostra os trade-offs de cada lado. A regra prática: componente de conteúdo que se repete vira bloco; página de campanha com visual elaborado fica no builder.

Pré-requisitos: Ambiente e ferramentas para o bloco

Antes de escrever a primeira linha de um bloco WordPress block editor, você precisa de quatro itens: Node.js 18 ou superior, npm, um WordPress 6.x local e um editor de código. O pacote @wordpress/create-block é a ferramenta oficial mantida pelo time do Gutenberg e gera todo o scaffold em um comando. Ele cria o block.json, o index.js, o edit.js e o package.json com as dependências corretas já apontadas.

Quatro ferramentas resolvem 90% do fluxo. O @wordpress/scripts compila o JSX e o SCSS sem você configurar Webpack na mão. O wp-env sobe um WordPress descartável via Docker em segundos. O functions.php entra só se você optar pelo registro manual em vez do plugin gerado. E o LocalWP serve como alternativa visual ao wp-env para quem prefere interface. Com esse ambiente pronto, o scaffold abaixo leva menos de um minuto. Se você ainda monta layouts no builder, o tutorial de CSS personalizado no Elementor cobre o outro caminho.

Passo a passo: Criar e registrar o bloco

O scaffold oficial gera um bloco WordPress block editor funcional em torno de 30 segundos e já o registra como plugin ativável. A partir dele, você edita os atributos, a interface de edição e a saída. Os cinco passos abaixo levam do comando inicial ao bloco visível no menu “+” do editor, com o block.json como fonte única de metadados (o padrão recomendado desde o WordPress 5.8).

Passo 1: Gere o scaffold com create-block

Rode npx @wordpress/create-block meu-bloco na pasta wp-content/plugins. O comando baixa o template oficial e cria uma pasta completa com block.json, código-fonte em src/ e o arquivo PHP de registro. Em segundos você tem um plugin pronto para ativar no painel.

Passo 2: Defina os atributos no block.json

Abra o block.json e declare os campos editáveis no objeto attributes. Cada atributo tem um tipo (string, boolean, number) e uma origem. É aqui que você decide o que o editor poderá alterar: um título, uma cor, um link. O block.json é lido pelo WordPress e pelo bundler ao mesmo tempo.

Passo 3: Construa a interface no edit.js

No edit.js, use os componentes do pacote @wordpress/block-editor, como RichText e InspectorControls, para montar a edição. Esse arquivo controla o que o usuário vê dentro do editor. Mantenha-o próximo da saída real para evitar o erro de “block validation” que aparece quando o HTML salvo diverge do esperado.

Passo 4: Compile com wp-scripts

Execute npm run build para o @wordpress/scripts transpilar o JSX e gerar os arquivos finais em build/. Para desenvolver com recarga automática, use npm start. O bundler resolve as dependências do WordPress sem incluí-las no pacote, mantendo o arquivo final enxuto.

Passo 5: Ative o plugin e teste no editor

Ative o plugin no painel, abra um post novo e clique no “+”. Seu bloco aparece na categoria definida no block.json. Insira-o, edite os campos e salve. Confirme que o HTML do front-end bate com a pré-visualização do editor para não disparar o aviso de bloco corrompido.

Bloco estático versus dinâmico: A decisão que define a arquitetura

A maioria dos casos de bloco WordPress block editor que um site precisa são estáticos, e essa escolha define se você escreve PHP ou não. Um bloco estático salva o HTML final no post: zero consulta ao banco em runtime, ideal para cards e avisos. Um bloco dinâmico usa um render_callback em PHP que monta o HTML em cada um dos carregamentos, somando 1 ou mais queries por visita.

O erro comum é tornar tudo dinâmico “por garantia”, o que adiciona consultas ao banco em cada visita. A regra: se o conteúdo é fixo no momento da edição, use estático. Se ele depende de dados externos ou que mudam, use dinâmico com cache. Para conteúdo que se repete sem lógica nova, um bloco reutilizável resolve sem código algum. Já blocos com campos complexos se beneficiam de blocos customizados com ACF PRO, que dispensa escrever React.

Erros comuns ao registrar um bloco WordPress block editor

Três erros respondem pela maioria dos tickets de bloco que chegam ao suporte: caminho errado no block.json, ausência de npm run build e divergência entre edit e save. O primeiro acontece quando o campo editorScript aponta para um arquivo que o build não gerou; o WordPress simplesmente não mostra o bloco. O segundo é esquecer de compilar: você edita o src/, mas o build/ continua antigo.

O terceiro erro é o mais traiçoeiro. Quando o HTML que o save.js produz não bate com o que está salvo no banco, o Gutenberg exibe “Este bloco contém conteúdo inesperado”. A causa quase sempre é mudar a estrutura do save depois de já ter salvo posts com a versão anterior. A correção é usar block deprecation para versionar a saída antiga. Quem prefere fugir desse risco pode montar o componente como um block pattern ou usar campos via ACF PRO, que renderiza por PHP e não sofre validação de HTML.

Quando o Elementor PRO faz mais sentido que um bloco nativo

Para uma landing page visual de prazo curto, o Elementor PRO entrega mais de 90 widgets prontos e arrastar-e-soltar, enquanto um bloco WordPress block editor exige escrever código do zero. É por isso que a maior parte das landing pages de cliente nasce no builder: o ganho de velocidade de produção supera o custo de peso. Para uma campanha pontual com visual elaborado, codar um bloco é desperdício de tempo.

A linha divisória é clara. Componente de conteúdo recorrente, leve e versionável: um bloco WordPress block editor. Página de marketing com layout único e muitos elementos visuais: builder. O FULL plano PRO inclui o Elementor PRO e o ACF PRO no mesmo bundle, junto de outros 15 plugins premium, por R$849,90 ao ano, o que sai em torno de R$85 por site quando você gerencia uma carteira de 10 sites. Comprados avulsos, só esses dois plugins já passam disso. Confira os planos da FULL para ver o que entra no PRO. A gente vê no suporte que muita agência paga caro por licenças separadas que o bundle já cobre.

Performance: O impacto real do bloco no Core Web Vitals

Sites que migram seções repetidas de page builder para um bloco WordPress block editor costumam reduzir o JavaScript enfileirado em uma fatia relevante, o que melhora diretamente o INP e o LCP. O mecanismo é o carregamento condicional de assets: o Gutenberg só enfileira o CSS e o JS de um bloco nas páginas onde ele aparece, enquanto o builder tende a carregar sua biblioteca completa em todo o site.

Na base da FULL (150 mil sites conectados), a maior parte dos sites com nota baixa de performance carrega bibliotecas que a página atual nem usa. Trocar um card de builder por um bloco nativo não conserta tudo, mas remove peso morto de cada carregamento. Combine isso com um plugin de cache e a entrega melhora de forma composta. Para entender o conjunto da otimização, o guia Domine o Elementor reúne os tutoriais de quem usa as duas abordagens. O ponto: bloco nativo é a escolha de performance; builder é a escolha de velocidade de produção.

Perguntas frequentes sobre bloco WordPress block editor

Próximos passos para dominar o block editor

Criar um bloco WordPress block editor deixa de ser intimidante quando você separa as três decisões: estático ou dinâmico, código ou ACF PRO, bloco nativo ou builder. O scaffold oficial com @WordPress/create-block remove a parte chata da configuração, e o block.json centraliza tudo num arquivo só. Comece com um bloco estático simples, valide a saída no editor e evolua para dinâmico só quando o conteúdo exigir. Para continuar aprendendo, o FULL Academy reúne tutoriais, guias e reviews de WordPress em um só lugar, do Gutenberg ao Elementor. O objetivo é claro: páginas mais leves, conteúdo reutilizável e menos dependência de licenças caras.

Legenda: o bloco personalizado aparece na categoria definida no block.json, ao lado dos blocos nativos.