WordPress 7.1: testes para o editor em iframe

O WordPress 7.1, lançado em 19 de agosto de 2026, torna o editor de posts sempre baseado em iframe. Isso vale independentemente do tipo de tema, da versão da Block API usada pelos blocos e da presença de metaboxes legadas. Para quem mantém temas e plugins, o ponto principal não é “se” o iframe será ativado, mas se CSS e JavaScript foram escritos para o documento correto e se interfaces auxiliares continuam funcionando quando o canvas do editor está isolado.

O risco de regressão é maior em extensões que alcançam o conteúdo do editor usando o document ou window global, em folhas de estilo que dependem da árvore DOM da tela administrativa e em bibliotecas que posicionam popovers ou escutam eventos sem considerar que o conteúdo editável vive em outro documento. A mudança é deliberada: a separação impede vazamento de estilos do wp-admin para o conteúdo, faz unidades de viewport e media queries refletirem o tamanho real do canvas e aproxima a renderização do editor do front-end.

O que muda no WordPress 7.1

Até o WordPress 7.0, o editor de posts ainda podia cair no modo sem iframe em determinados cenários de compatibilidade. No 7.1, esse fallback deixa de ser a referência: o canvas do post fica em iframe mesmo quando o conteúdo usa blocos antigos. O Gutenberg 23.6 ou posterior já força esse comportamento e pode ser usado como ambiente de teste.

Blocos legados não impedem o iframe. A presença de blocos com Block API anterior à versão 3 não é mais uma saída para manter o editor no documento principal.
Metaboxes não impedem o iframe. O suporte a metaboxes já vinha sendo adaptado em versões anteriores, e o 7.1 mantém o canvas isolado mesmo quando elas existem.
O editor e o conteúdo do editor são contextos diferentes. Controles, sidebars e plugins da interface ficam no contexto administrativo; o conteúdo editável fica no documento do iframe.
CSS e JavaScript precisam ser carregados no destino correto. Um asset presente na página administrativa não está automaticamente no mesmo contexto DOM do conteúdo do canvas.

Matriz de testes antes de atualizar o site

Área	O que testar	Sinal de regressão	Ação provável
CSS do conteúdo	Tipografia, espaçamentos, largura, estados responsivos, seletores de blocos e estilos do tema dentro do canvas	Bloco sem estilo, regra que só funciona no front-end ou layout diferente do esperado	Revisar onde o CSS é enfileirado e remover dependência de ancestrais do wp-admin
CSS da interface	Inspector, toolbar, sidebar e componentes adicionados pelo plugin	Controles desformatados ou estilos vazando para o conteúdo	Manter assets da interface no hook próprio do editor e não misturá-los com CSS do conteúdo
DOM e eventos	Seleção de elementos, listeners de mouse/teclado, resize, scroll, drag-and-drop e medições de posição	querySelector não encontra o bloco, atalho não dispara ou listener é registrado no documento errado	Derivar ownerDocument e defaultView de um elemento do canvas e limpar listeners quando a referência mudar
Metaboxes	Campos, salvamento, abas, dropdowns, calendários, modais e popovers	Popover cortado, campo inacessível ou interação que perde foco	Evitar UI que estoure o contêiner da metabox ou renderizar popovers fora dele
Rich text	Formatos personalizados, links, tooltips e UI ancorada à seleção de texto	Popover abre longe da seleção ou foco volta para o lugar errado	Usar APIs de ancoragem compatíveis com iframe, como useAnchor, em vez de cálculos globais
Bibliotecas externas	Carrosséis, masonry, editores, pickers e libs que leem window/document	Funciona no front-end e falha apenas no editor	Inicializar pela referência do elemento e, se necessário, corrigir a biblioteca para aceitar o documento relativo
Blocos antigos	Posts reais com blocos API v1/v2, blocos dinâmicos e extensões de blocos de terceiros	Erro que não aparecia no 7.0 porque o editor saía do iframe	Corrigir compatibilidade e migrar blocos próprios para apiVersion 3 após o teste

CSS: separe estilos do conteúdo dos estilos da interface

A primeira revisão deve responder a uma pergunta simples: a regra estiliza o conteúdo editável ou a interface do editor? A documentação do WordPress recomenda enqueue_block_editor_assets para scripts e estilos da interface do editor — por exemplo, controles de inspector, toolbar, variações e plugins do editor. Para assets que precisam alcançar os blocos no canvas, enqueue_block_assets é o caminho principal; desde o WordPress 6.3 esses assets também são carregados no editor em iframe e continuam disponíveis no front-end.

Teste especialmente seletores que começam no body do wp-admin, atravessam wrappers administrativos ou presumem que o bloco é descendente direto da página do editor. Com o iframe, o conteúdo não compartilha essa árvore de ancestrais. Regras que dependem de algo como “body administrativo + wrapper do editor + bloco” tendem a parar de casar. Em contrapartida, seletores focados no próprio bloco e estilos declarados via theme.json ou pelas APIs de estilo do bloco ficam mais alinhados ao modelo isolado.

Também compare breakpoints, vw/vh e layouts fluidos. Um benefício do iframe é justamente fazer media queries e unidades relativas ao viewport responderem às dimensões do canvas, não à largura total da página administrativa. Uma diferença visual nessa área pode ser correção de comportamento, não necessariamente bug; o critério deve ser a proximidade com o front-end.

JavaScript e o risco de document/window apontarem para o lugar errado

O ponto técnico mais citado pela equipe do WordPress é que o iframe possui seu próprio document e window. Scripts do editor normalmente executam na página administrativa, portanto usar os globais para procurar um elemento do canvas, medir a janela ou registrar eventos pode atingir o documento pai em vez do documento onde o bloco existe.

Para código React de blocos, a recomendação é obter uma referência para um elemento renderizado no canvas e, a partir dele, usar ownerDocument para chegar ao documento correto e defaultView para chegar à janela correspondente. Para listeners, o WordPress recomenda useRefEffect porque ele permite instalar e remover o listener quando a referência do elemento muda, algo importante em re-renderizações e remontagens do canvas.

O teste deve cobrir eventos de teclado, mouse, pointer, scroll e resize; APIs de seleção; medições com retângulos de layout; drag-and-drop; portais; e qualquer busca feita com seletores globais. Se um recurso “some” apenas dentro do editor, abra o console e confirme em qual document o código está procurando os elementos antes de concluir que há erro no bloco em si.

Metaboxes: o iframe não significa que elas desapareceram

Metaboxes clássicas continuam sendo um caso de compatibilidade importante. A mudança do 7.1 não exige removê-las para que o editor funcione, mas elimina a expectativa de que sua presença desative o iframe. Por isso, plugins que nunca foram testados nessa combinação podem revelar problemas agora.

Há dois pontos de atenção já documentados pelo projeto. O primeiro é overflow: o contêiner da metabox pode cortar elementos que escapam de seus limites, especialmente menus e popovers que abrem para cima. Componentes do pacote @wordpress/components, como Popover e Dropdown, evitam esse problema ao renderizar a camada em uma região adequada da interface. Se o plugin usa uma solução própria, teste calendários, autocompletes, selects avançados e menus em diferentes alturas da página.

O segundo é UI ancorada a seleção de rich text. Plugins que adicionam formatos de texto, tooltips ou pequenos editores flutuantes não devem calcular a posição supondo um único documento. A API useAnchor, de @wordpress/rich-text, é a referência recomendada para esse tipo de ancoragem.

Plugins com bibliotecas de terceiros merecem uma rodada separada

Uma biblioteca pode receber corretamente o elemento do bloco e ainda acessar window ou document global internamente. Isso aparece com frequência em componentes de drag, zoom, masonry, pickers e widgets antigos. O guia de migração do WordPress recomenda preferir bibliotecas que aceitem um elemento-alvo e derivem dele o documento. Quando a dependência está fora do seu controle, a solução sustentável é corrigir a biblioteca ou enviar um patch upstream; usar a cópia da biblioteca carregada dentro do iframe pode servir como transição, mas não é o caminho preferido.

Com jQuery ou plugins jQuery, passe o elemento do bloco para a inicialização em vez de procurar novamente o nó a partir do document global. Também confirme a destruição do componente quando o bloco for desmontado, para não acumular listeners, observers ou instâncias órfãs ao alternar modos do editor.

Block API v3 continua importante, mas não controla mais o iframe

Migrar blocos próprios para apiVersion 3 continua recomendado porque essa versão sinaliza compatibilidade com o editor em iframe e é o padrão da documentação atual. A diferença é que, no WordPress 7.1, manter apiVersion 1 ou 2 não devolve o editor ao modo antigo. Portanto, “funciona porque ainda está em API v2” deixa de ser uma estratégia de compatibilidade.

Na prática, trate a API v3 como parte da modernização do bloco, não como um interruptor do iframe. Primeiro reproduza o comportamento em uma cópia do site, corrija dependências de DOM e assets e só então atualize a declaração do bloco, validando edição, salvamento, reabertura e renderização no front-end.

Roteiro de teste em staging

Clone uma amostra realista. Inclua posts antigos, blocos personalizados, blocos de terceiros, metaboxes, campos complexos e conteúdo que use padrões responsivos.
Teste com WordPress 7.1 na mesma pilha de plugins do site. Se precisar antecipar o comportamento em outra instalação, Gutenberg 23.6 ou posterior força o post editor em iframe.
Abra o console e a aba de rede. Procure erros JavaScript, assets 404, estilos ausentes e avisos que só aparecem ao editar.
Inspecione o iframe. Confirme se folhas de estilo destinadas ao conteúdo realmente foram carregadas dentro do documento do canvas.
Exercite interações. Inserir, selecionar, duplicar, mover, arrastar, usar atalhos, abrir popovers, editar rich text, alternar sidebars e trabalhar com metaboxes.
Salve e reabra. Uma integração pode parecer correta durante a sessão e falhar no ciclo de serialização, persistência de meta ou remontagem do bloco.
Compare com o front-end. Verifique tipografia, espaçamento, breakpoints, largura e estados responsivos para detectar divergências reais.
Teste os plugins mais sensíveis isoladamente. Se houver falha, repita com os demais plugins desativados para separar conflito de incompatibilidade direta com iframe.

Checklist de liberação

CSS do conteúdo chega ao documento do iframe e não depende de ancestrais do wp-admin.
CSS e scripts da interface usam o contexto administrativo apropriado.
Nenhum recurso do bloco depende de document/window global para alcançar o canvas.
Listeners e observers são removidos quando o elemento é remontado ou desmontado.
Popovers e dropdowns de metaboxes não são cortados.
Formatos de rich text mantêm posição, foco e seleção dentro do iframe.
Bibliotecas externas recebem um elemento-alvo e funcionam sem pressupor um único window/document.
Posts com blocos antigos abrem, editam, salvam e reabrem sem erro.
O resultado visual do editor continua coerente com o front-end em diferentes larguras.
Há backup e caminho de rollback antes de aplicar a atualização em produção.

Fontes oficiais para conferir durante a migração

A regra prática é simples: não use o fato de um plugin ter funcionado no editor de posts do WordPress 7.0 como prova de compatibilidade. O 7.1 remove o fallback que ainda escondia parte dos problemas. Se CSS, DOM, foco, metaboxes e bibliotecas forem testados no documento correto, a transição tende a ser previsível e o isolamento do iframe passa a trabalhar a favor da consistência do editor.