Query Loop Block no WordPress: Listar Posts com o Editor de Blocos

O Query Loop block no WordPress substitui o antigo loop PHP por uma interface visual no editor de blocos. Com ele, qualquer editor consegue listar posts, filtrar por categoria, paginar resultados e definir o que aparece quando nao ha nada para exibir, tudo sem escrever uma linha de codigo. Depois de configurar mais de 300 sites em WordPress, a Weboption viu essa funcionalidade amadurecer bastante desde o WordPress 5.8 e hoje ela resolve boa parte dos casos de uso que antes exigiam um plugin de query customizada ou um tema filho cheio de PHP.

O que e o Query Loop Block e para que serve

O Query Loop block e um bloco nativo do WordPress que executa uma consulta ao banco de dados e renderiza os resultados com blocos filhos. Em termos praticos, ele faz o que o WP_Query faz no PHP, so que configuravel pelo painel. A Automattic investiu pesado nele: desde o WordPress 6.0, o bloco suporta heranca de contexto, o que significa que um template de arquivo pode passar o post atual para blocos internos sem truques.

Um dado importante: segundo a pesquisa State of the Word 2024, mais de 60% dos novos temas publicados no diretorio oficial usam o editor de site completo (FSE), e o Query Loop e o bloco mais usado nesses temas. Ignorar esse bloco hoje e optar por complexidade desnecessaria.

Como configurar o Query Loop Block passo a passo

A configuracao comeca inserindo o bloco via /query no editor. O WordPress oferece alguns padroes visuais de layout, mas voce pode comecar do zero com uma grade ou lista. O painel lateral e onde o trabalho real acontece.

No campo “Tipo de post”, selecione o post type que deseja listar. O padrao e post, mas qualquer CPT registrado com show_in_rest: true aparece aqui. Esse detalhe de show_in_rest pega muita gente desprevenida, como veremos adiante.

Em seguida defina quantos itens por pagina quer exibir. O recomendado para performance e entre 9 e 12 itens, considerando que cada item dispara consultas de imagem. Acima de 20 itens por pagina, os Largest Contentful Paint scores caem visivelmente em sites com imagens de qualidade.

O campo “Ordem” permite classificar por data, titulo, numero de comentarios ou ordem de menu. Para listagens de blog padrao, data decrescente ainda e o formato mais lido. Para portfolios ou produtos, a ordem de menu da muito mais controle editorial.

Filtros por categoria, tag e autor

O Query Loop block filtra por taxonomia diretamente no painel, sem precisar de shortcodes ou plugins. Abra “Filtros” no inspector e voce encontra campos para categoria, tag e autor.

Uma ressalva pratica: ao filtrar por categoria, o bloco usa IDs numericos internamente, nao slugs. Isso significa que se voce exportar o conteudo para outro ambiente e as categorias tiverem IDs diferentes, os filtros quebram silenciosamente. A Weboption resolve isso sempre documentando o mapeamento de IDs em migracao ou usando o bloco de filtro interativo do Query Filter, disponivel desde o WordPress 6.1, que referencia por slug.

O filtro por autor e especialmente util em sites com multiplos colaboradores. Em vez de criar uma pagina de arquivo por autor na mao, um Query Loop block com o autor fixo resolve em segundos. Para revistas e portais de noticias isso economiza horas de desenvolvimento.

Tags funcionam da mesma forma que categorias. Voce pode combinar multiplas tags com logica OR ou AND. A logica AND e mais restritiva e por isso tende a retornar poucos resultados. Use com cuidado em sites com taxonomias esparsas.

Query Loop com Custom Post Types

Usar o Query Loop block com tipos de post personalizados e onde a ferramenta realmente brilha. Um CPT de “Projetos”, “Imobiliarios” ou “Profissionais de saude” pode ter seu proprio arquivo visual sem que o desenvolvedor precise editar um arquivo PHP.

O requisito tecnico e simples: o CPT precisa ser registrado com 'show_in_rest' => true. Sem isso, o bloco nao enxerga o tipo de post. Tambem e necessario que o CPT tenha 'has_archive' => true se voce quiser que o WordPress gere automaticamente uma URL de arquivo para ele.

Com o ACF (Advanced Custom Fields) na versao 6.x, campos personalizados podem ser usados nos blocos internos do Query Loop via bloco de campo ACF. O preco do ACF Pro e atualmente R$ 420 por ano para uso em um site, e a integracao com o editor de blocos ficou bem mais estavel a partir da versao 6.2 lancada em 2024.

Paginacao e tratamento de resultados vazios

A paginacao no Query Loop block e um bloco filho chamado “Paginacao de consulta”. Adicione-o dentro do template de post e ele aparece automaticamente quando o numero de resultados excede o limite configurado.

O bloco de paginacao tem tres variantes: numerada, anterior/proxima e um botao de carregar mais (modo AJAX). O modo AJAX, chamado de “Carregar mais”, nao recarrega a pagina e e tecnicamente superior para experiencia do usuario. A ressalva e que ele requer JavaScript habilitado e pode conflitar com alguns plugins de cache mal configurados que armazenam o estado da pagina com os posts ja carregados.

Para o tratamento de resultados vazios, existe o bloco “Nenhum resultado” dentro do Query Loop. Ele aparece apenas quando a consulta nao retorna posts. Coloque uma mensagem util aqui, nao apenas “Nenhum post encontrado”. Sugerimos algo como “Ainda nao temos conteudo nessa categoria. Explore nossos outros artigos abaixo” com um link para o blog principal. Pequeno detalhe, grande diferenca em taxa de rejeicao.

Blocos internos e personalizacao do template de post

O Query Loop block funciona como um container. Dentro dele existe o “Template de post de consulta”, que define o que aparece para cada item da lista. Os blocos que voce pode usar dentro dele incluem imagem destacada, titulo do post, trecho, data, autor, categorias e tags, alem de blocos de campo do ACF e qualquer bloco personalizado que declare suporte a contexto de post.

Uma configuracao comum na Weboption para blogs e: imagem destacada com proporcao 16:9, titulo linkado, data de publicacao, trecho de duas linhas e link “Leia mais”. Essa estrutura converte bem e carrega rapido porque evita o peso de meta fields extras.

Para grids de portfolio, trocamos o trecho pela imagem ampliada e o titulo vai abaixo, o que e mais visual. O editor consegue alterar isso sem ajuda tecnica, o que e o ponto central do bloco.

Erro que vemos com frequencia

O erro mais comum que encontramos em auditorias de sites WordPress com Query Loop block e usar o bloco sem definir o contexto correto em templates de arquivo. O que acontece: o desenvolvedor cria um template de categoria via FSE e adiciona um Query Loop block, mas esquece de ativar a opcao “Herdar consulta do modelo”. O resultado e que o arquivo de categoria lista todos os posts do site em vez de apenas os posts daquela categoria.

A opcao “Herdar consulta do modelo” fica na parte superior do painel de configuracao do bloco. Quando ativada, o bloco usa a consulta que o WordPress ja determinou para aquela URL, seja um arquivo de categoria, tag, autor ou busca. Quando desativada, voce define a consulta manualmente. Em templates de arquivo, quase sempre voce quer a opcao ativada.

Outro erro recorrente: colocar o bloco de paginacao fora do Query Loop block. Fora do contexto do bloco pai, a paginacao nao funciona. Ele precisa estar aninhado dentro do template de post de consulta ou diretamente dentro do Query Loop.

Perguntas frequentes

O Query Loop block funciona com temas classicos do WordPress?

Nao diretamente. O Query Loop block e parte do editor de blocos e funciona em temas com suporte a blocos. Em temas classicos, o bloco pode ser inserido em paginas e posts usando o editor Gutenberg, mas nao e possivel usa-lo em templates PHP do tema sem habilitar o editor de site completo ou usar um plugin de compatibilidade.

Posso filtrar posts por campo personalizado no Query Loop block?

A filtragem nativa por meta fields nao existe na interface visual ainda, mas e possivel via filtro PHP usando o hook query_loop_block_query_vars disponivel desde o WordPress 6.1. Plugins como o Meta Query Block (gratuito) tambem adicionam essa funcionalidade sem codigo.

O Query Loop block afeta a performance do site?

O bloco em si e eficiente, mas o numero de posts por pagina e a complexidade dos blocos internos impactam o tempo de carregamento. Mantenha ate 12 itens por pagina, use lazy loading nas imagens destacadas e evite blocos que disparam requisicoes extras por item. Com essas praticas, o bloco nao representa gargalo de performance.

Como usar o Query Loop block para criar uma pagina de busca personalizada?

Crie um template de arquivo de busca no editor de site e adicione um Query Loop block com a opcao “Herdar consulta do modelo” ativada. O WordPress passa automaticamente o termo de busca para o bloco. Adicione o bloco “Nenhum resultado” para tratar buscas sem retorno, o que melhora bastante a experiencia do usuario.

O Query Loop block substitui o WP_Query completamente?

Para a maioria dos casos de uso editoriais, sim. Casos que ainda exigem WP_Query diretamente no PHP incluem consultas com joins em tabelas customizadas, logica condicional complexa baseada no usuario logado e integracao com sistemas externos. Para listagens de posts, arquivos e CPTs, o bloco cobre praticamente tudo sem codigo.