💡 Como adicionar uma janela popup no WordPress

• Escolha a sua abordagem: o plugin Popup Maker para um arranque rápido ou código personalizado para controlo total
• Instale o Popup Maker através de «Plugins → Adicionar Novo» e ative-o
• Crie um novo popup, defina o conteúdo do artigo ou página e configure um gatilho (clique, temporizador ou scroll)
• Para uma solução personalizada, adicione os estilos CSS da janela modal ao ficheiro do seu tema ou ao personalizador
• Carregue o ficheiro JavaScript via wp_enqueue_script() com dependência do jquery, verificando a ordem de carregamento
• Abra a página e teste o popup no seu navegador, monitorizando a consola para detetar erros

O que são janelas modais e porque é que o seu site WordPress precisa delas

Uma janela modal é um bloco de conteúdo popup que se abre sobre a página, escurecendo o fundo. O utilizador nunca sai do URL atual, mas vê informação adicional: texto de artigo, um formulário, um vídeo ou uma galeria.

Para um site WordPress, as janelas modais resolvem três problemas específicos. Primeiro, um painel de utilizador: em vez de uma página de perfil separada, exibe definições, encomendas ou mensagens num bloco popup. Segundo, pré-visualização rápida de conteúdo: um visitante clica num cartão de produto ou teaser de artigo e vê o conteúdo completo sem recarregar. Terceiro, formulários de captação de leads: formulários de subscrição, registo e contacto aparecem exatamente quando o visitante está pronto para agir.

A principal vantagem de uma janela modal em relação a uma página separada é a velocidade. Não há espera pelo carregamento completo de uma página com cabeçalho, barra lateral e rodapé. Carrega apenas the_content(), conteúdo puro. Isto poupa tempo ao utilizador e recursos do servidor.

WP Post Popup: porque é que o plugin veterano saiu de cena

Até 2023, uma das soluções mais populares para janelas modais no WordPress era o plugin WP Post Popup (wp-post-modal). Conseguia transformar qualquer artigo, página ou tipo de publicação personalizado num popup; bastava especificar um URL com um parâmetro. O plugin funcionava com shortcodes, Contact Form 7 e BuddyPress; conseguia carregar páginas externas e até exibir seletivamente uma div específica de outro site.

Em outubro de 2023, o plugin foi encerrado. O motivo foi uma vulnerabilidade de segurança. A página do WordPress.org mostra agora o estado «Este plugin foi encerrado… Motivo: Problema de Segurança». Desde então, está indisponível para download e as instalações ativas caíram para zero.

Mas as ideias por detrás do WP Post Popup não desapareceram. A tarefa de exibir conteúdo num popup sem recarregar ainda é solucionável hoje, e por duas vias: plugins modernos e código puro.

3 Formas modernas de adicionar uma janela modal no WordPress

Aqui estão as opções atuais para 2026, desde plugins prontos a uma solução totalmente personalizada.

Popup Maker é o plugin gratuito mais popular para popups: mais de 700.000 instalações ativas e uma classificação de 4,9 no WordPress.org. Cria qualquer tipo de popup, desde janelas modais com conteúdo a painéis deslizantes e banners. Os gatilhos incluem clique, temporizador, scroll ou intenção de saída. Se precisa de uma solução rápida sem código, este é o melhor ponto de partida.

Bootstrap 5 está integrado em muitos temas modernos. O seu componente Modal nativo funciona de imediato: responsividade, animação, fecho ao premir Escape e ao clicar fora da janela. Basta incluir o Bootstrap no seu tema e usar a marcação pronta com atributos de dados.

Código puro é o caminho para quem precisa de controlo total sobre cada pixel e comportamento da janela. Sem scripts extra, dependências ou conflitos com outros plugins. Este é o método que vamos percorrer passo a passo.

O vídeo acima é um tutorial prático para criar uma janela modal personalizada no WordPress de raiz: 12 minutos de código puro com um resultado pronto no final.

Guia passo a passo: construir uma janela modal de raiz

Este método funciona em qualquer site WordPress, independentemente do tema. Vamos escrever uma estrutura CSS para estilizar o bloco popup, corrigir um erro típico de JavaScript e adicionar um pré-carregador inteligente para que o conteúdo apareça suavemente, sem cintilações.

Passo 1: Estrutura CSS para a janela modal

O estilo básico realiza três coisas: centra a janela no ecrã, escurece o fundo e adapta tabelas dentro do bloco modal. Aqui está o código funcional para o ficheiro style.css do seu tema ou para o separador «CSS Adicional» no personalizador:

1
/* Modal window — basic styles */
2
.modal.show {
3
    max-width: 650px;
4
}
5
 
6
.modal.show .kk-star-ratings.bottom-right.rgt {
7
    display: none;
8
}
9
 
10
/* Tables inside the modal window */
11
.modal.show table {
12
    border-collapse: separate;
13
    max-width: 100%;
14
    overflow: auto;
15
    table-layout: fixed;
16
    border: none;
17
    width: auto;
18
}
19
 
20
.modal.show table th {
21
    background: #F8F0F8;
22
    padding: 17px 10px;
23
    vertical-align: middle;
24
    color: #7F617E;
25
    font-size: 12px;
26
    text-align: left;
27
}
28
 
29
.modal.show table th:first-child {
30
    border-radius: 5px 0 0 5px;
31
}
32
 
33
.modal.show table th:last-child {
34
    border-radius: 0 5px 5px 0;
35
}
36
 
37
.modal.show table th.th-border {
38
    border-left: 1px solid #ECE1EC;
39
}
40
 
41
.modal.show table td {
42
    color: #424242;
43
    font-size: 13px;
44
    border-bottom: 1px dashed #E5E5E5;
45
    padding: 10px 5px 5px 4px;
46
    text-align: left;
47
}
48
 
49
.modal.show table tr:last-child td {
50
    border-bottom: none;
51
    padding-bottom: 20px;
52
}
53
 
54
.modal.show table td {
55
    border-right: 1px solid #F7F7F7;
56
}
57
 
58
.modal.show table td:last-child {
59
    border-right: none;
60
}
61
 
62
.modal.show table tr:first-child td {
63
    padding-top: 20px;
64
}

O ponto-chave: o seletor .modal.show garante que os estilos se aplicam apenas quando a janela modal está ativa. No estado recolhido, o bloco não afeta o layout da página. As tabelas dentro do bloco modal recebem um tratamento separado: cantos arredondados nos cabeçalhos, divisores de linha a tracejado e scroll responsivo.

Passo 2: Erros de JavaScript e como corrigi-los

O problema mais comum ao trabalhar com janelas modais no WordPress é o erro Uncaught ReferenceError: wp is not defined. Ocorre quando um plugin ou script personalizado tenta usar o objeto wp (a API JavaScript do WordPress) antes de o núcleo o ter carregado.

No caso do WP Post Popup, o problema estava na função modalCustomizer(), que obtinha definições do administrador via wp.customize. Eis como aparecia no código do plugin:

1
// Window load
2
$(window).on('load', function () {
3
    modalCustomizer();
4
});

A correção é simples: comente a chamada se estilizar a janela através do seu próprio CSS:

1
// Window load
2
$(window).on('load', function () {
3
    // modalCustomizer();
4
});

Uma regra geral para quaisquer scripts modais no WordPress: verifique sempre a ordem de carregamento das dependências. Carregue os seus scripts via wp_enqueue_script() com dependências explícitas de jquery e wp-util. E nunca insira <script> diretamente no corpo de um artigo; esse é um caminho certo para erros como $ is not defined e wp is not defined.

Passo 3: Pré-carregador inteligente com jQuery

A função do pré-carregador é mostrar um indicador de carregamento enquanto o conteúdo do artigo é carregado via AJAX. Assim que os dados chegam, o pré-carregador desaparece suavemente. Para monitorizar alterações no DOM, usamos a micro-biblioteca jquery-watch (25 linhas de código que monitorizam alterações de atributos e propriedades num elemento).

CSS para o pré-carregador: um indicador gif de fundo centrado no bloco modal:

1
/* Modal window preloader */
2
.modal-wrapper.styled .modal {
3
    min-height: 385px;
4
    background-color: white;
5
    background-size: inherit;
6
}
7
 
8
div#modal-content {
9
    background-color: white;
10
}
11
 
12
.modal-wrapper.styled .modal {
13
    background: white url(/wp-content/uploads/2018/02/dollar-glass.gif) center center no-repeat scroll;
14
}
15
 
16
#single-post-meta-manager {
17
    opacity: 0;
18
}
19
 
20
div.modal-content-post-wrapped.load {
21
    opacity: 1;
22
}

Como funciona: inicialmente o conteúdo está oculto (opacity: 0) e o pré-carregador de fundo está visível. Quando os dados são carregados, o jQuery adiciona a classe .load, o conteúdo aparece gradualmente e o pré-carregador desaparece. Aqui está o código JS:

1
jQuery(document).ready(function($) {
2
 
3
    // Smooth appearance of content in the modal window
4
    $("div#single-post-meta-manager").animate({ 'opacity': '1' }).fadeIn('slow');
5
 
6
    // Add class-informer "content loaded"
7
    $("div.modal-content-post-wrapped").addClass("load");
8
 
9
    // Track modal window changes via jquery-watch
10
    $(".modal-wrapper").watch({
11
        properties: "top,left,opacity,display,attr_class",
12
        watchChildren: true,
13
        callback: function (data, i) {
14
            // Set preloader as background image
15
            $('.modal-wrapper.styled .modal').css(
16
                'background',
17
                'white url(/wp-content/uploads/2018/02/dollar-glass.gif) center center no-repeat scroll'
18
            );
19
            // If content is loaded — remove preloader
20
            if ($('.modal-content-post-wrapped').is('.load')) {
21
                $('.modal.show').css('background', 'white');
22
            }
23
        }
24
    });
25
 
26
});

Aviso importante. O código acima usa jQuery e o plugin jquery-watch. Antes de o inserir, certifique-se de que o jQuery está carregado e é executado antes do seu script. Em sites WordPress modernos, o jQuery é distribuído com o núcleo, pelo que não são necessárias inclusões adicionais. Adicione o script via wp_enqueue_script() no functions.php, não diretamente no corpo do artigo.

O que fazer se a janela modal não carregar

Ao longo de mais de 6 anos a trabalhar com modais no WordPress, compilei uma lista de causas típicas, das óbvias às mais obscuras. Aqui está uma lista de verificação de diagnóstico:

• O jQuery não está carregado ou está em conflito. Verifique a consola do navegador (F12 → Consola). O erro $ is not defined significa que o jQuery não foi carregado ou o seu script foi executado demasiado cedo. Solução: wp_enqueue_script('my-modal', ..., array('jquery')).
• O modelo de página não produz the_content(). Alguns modelos personalizados como page-modal.php usam get_the_content() em vez de the_content(). O primeiro não aplica filtros, pelo que os shortcodes e a formatação se quebram.
• Conflito com plugins de cache. Se carrega conteúdo AJAX e o site usa WP Rocket ou LiteSpeed Cache, desative a cache para os URLs que a janela modal vai buscar.
• Erro de CORS ao carregar uma página externa. O navegador bloqueia pedidos para um domínio diferente. Isto resolve-se fazendo proxy através da API REST do WordPress ou configurando cabeçalhos CORS no servidor de destino.
• Breakpoint. Em dispositivos móveis, a janela modal é frequentemente substituída por um link direto para que o utilizador simplesmente navegue para a página. Verifique as regras @media no seu CSS: abaixo de 768px, a janela pode não aparecer intencionalmente.

⁉️🤔 Perguntas frequentes

Plugin ou código puro: o que devo escolher para uma janela modal?

Se precisa de uma solução pronta em 5 minutos, instale o Popup Maker. Cobre a maioria dos cenários típicos: formulários de subscrição, pré-visualizações rápidas, notificações. Se tem um design não padronizado, lógica AJAX complexa ou requisitos de desempenho (nem mais um kilobyte), escreva à mão. O código puro dá controlo total ao custo de algumas horas de desenvolvimento. O Popup Maker adiciona cerca de 40 a 60 KB de scripts e estilos a uma página. Uma solução personalizada cabe em 2 a 5 KB, uma diferença de 10 a 30 vezes. Para um site de alto tráfego, isso é notório.

Posso abrir uma página externa numa janela popup?

Sim, mas com limitações. O WordPress não faz proxy de conteúdo de terceiros por defeito. Se o site de destino não enviar o cabeçalho CORS Access-Control-Allow-Origin: *, o navegador bloqueará o pedido AJAX. A solução alternativa é escrever o seu próprio proxy do lado do servidor usando wp_remote_get() ou configurar um endpoint da API REST que obtenha o conteúdo e o entregue ao seu frontend. Para APIs públicas e fontes confiáveis, o CORS já está tipicamente configurado. A API do GitHub e a API do WordPress.org estão abertas para leitura a partir de qualquer domínio.

Como é que o uso de janelas modais afeta o SEO?

O conteúdo dentro de uma janela modal carregado via AJAX é menos visível para os motores de busca do que o HTML estático numa página dedicada. A regra é simples: se o conteúdo é importante para o ranking, deve ter a sua própria página canónica com um URL direto. Use a janela modal como um ponto de entrada adicional, não como substituto de uma página. O Googlebot executa JavaScript desde 2019, mas a indexação de conteúdo carregado dinamicamente ainda é instável. É melhor jogar pelo seguro e ter uma versão estática.

Porque foi o WP Post Popup encerrado e o que o pode substituir?

O plugin wp-post-modal foi encerrado em outubro de 2023 devido a uma vulnerabilidade de segurança não resolvida. Se ainda estiver instalado no seu site, remova-o imediatamente. Como substitutos, considere o Popup Maker (gratuito, universal) ou a solução personalizada descrita neste artigo. Ambas as opções são seguras e suportadas em 2026.

O jQuery é necessário para uma janela modal no WordPress?

Não, não é necessário. O JavaScript nativo moderno (ES6+) cobre todas as operações necessárias: fetch() para AJAX, classList para alternar classes CSS e addEventListener para lidar com cliques. No entanto, o jQuery ainda está profundamente integrado no núcleo do WordPress e na maioria dos temas, pelo que é mais fácil usar o que já está carregado do que incluir mais uma framework.

Janelas modais em 2026: o que instalar e como construir

Se chegou a esta secção, tem três caminhos prontos. Popup Maker é para quem precisa de uma solução «instalar e esquecer». 700 mil instalações ativas não mentem: o plugin é estável, flexível e gratuito na sua versão básica. Modal do Bootstrap 5: se o seu tema já corre em Bootstrap, use o componente nativo e não crie dependências extra. Código puro é para perfeccionistas e para quem quer controlar cada linha.

Pessoalmente, em 2026 escolho o segundo ou terceiro caminho. Os plugins para janelas modais resolvem o problema aqui e agora, mas o código personalizado resolve-o para sempre, sem atualizações, vulnerabilidades ou conflitos. E 2 a 5 KB em vez de 40 a 60 KB por página é um argumento difícil de ignorar.

Experimente ambas as abordagens num subdomínio de teste e compare. O WordPress sobreviveu 20 anos precisamente porque oferece liberdade de escolha, do código zero a um plugin pronto num minuto.