AJAX WordPress

AJAX WordPress é a técnica que permite trocar dados entre o navegador e o servidor sem recarregar a página inteira. O usuário envia um filtro, vota em uma enquete ou carrega mais posts e o WordPress responde no mesmo instante, atualizando só o trecho necessário do HTML. O CMS já vem com uma API AJAX nativa pronta para plugins e temas, com endpoint próprio em admin-ajax.php.

O que é AJAX no WordPress

AJAX significa Asynchronous JavaScript and XML. É um padrão da web que permite ao navegador disparar requisições em segundo plano enquanto o usuário continua usando a página. No WordPress, esse padrão ganha um endpoint padronizado e um conjunto de hooks que qualquer plugin ou tema pode usar.

Antes do AJAX, cada interação exigia recarregar a página inteira: votar, comentar, filtrar, paginar. Hoje, sites como WooCommerce usam AJAX para atualizar o mini-carrinho, calcular frete e aplicar cupons sem nenhum reload. A experiência fica mais próxima de um app do que de um site estático.

O ajax wordpress é especialmente útil em três cenários: formulários que não devem perder o estado da página (login, contato, busca), interações em tempo real (likes, contadores, votação) e listagens dinâmicas (filtros de produto, paginação infinita, autocompletar). Em todos eles, o ganho de UX é direto.

Existem dois canais oficiais para fazer AJAX no WordPress: o veterano admin-ajax.php, presente desde 2008, e a REST API moderna, introduzida em 2016. Os dois coexistem e cada um tem seu lugar — boa parte dos plugins ainda usa admin-ajax.php por compatibilidade.

Como funciona admin-ajax.php

O admin-ajax wordpress é um arquivo localizado em wp-admin/admin-ajax.php. Apesar do nome, ele atende requisições do front-end também, não apenas do painel. É o ponto único onde toda chamada AJAX nativa do WordPress chega antes de ser despachada para o handler correto.

O fluxo é simples: o JavaScript faz um POST para admin-ajax.php enviando um parâmetro chamado action, que identifica qual handler deve responder. O WordPress lê esse parâmetro e dispara dois hooks possíveis: wp_ajax_{action} para usuários logados e wp_ajax_nopriv_{action} para visitantes anônimos. Quem registrou esses hooks via add_action no functions.php ou em um plugin executa a lógica e devolve a resposta.

O wp_ajax do WordPress trabalha por padrão com JSON. As funções wp_send_json_success e wp_send_json_error encerram a requisição já formatadas. No lado JavaScript, a biblioteca jQuery vem embutida no core e oferece $.ajax e $.post como atalhos, mas nada impede usar fetch nativo.

Como qualquer endpoint que recebe input do usuário, requisições AJAX precisam validar permissões e proteger contra CSRF. O sistema de nonces do WordPress resolve isso: você gera um nonce no PHP via wp_create_nonce, envia junto com a requisição AJAX e valida no handler com check_ajax_referer.

Como implementar AJAX no WordPress

O primeiro passo é registrar o handler PHP. No functions.php do tema ou em um plugin, adicione duas linhas: add_action(‘wp_ajax_minha_acao’, ‘meu_handler’) e add_action(‘wp_ajax_nopriv_minha_acao’, ‘meu_handler’). A primeira atende usuários logados, a segunda atende visitantes anônimos. Se o handler for restrito, registre só a primeira.

Dentro do handler, valide o nonce com check_ajax_referer, sanitize todos os campos com funções como sanitize_text_field e absint, execute a lógica e responda com wp_send_json_success ou wp_send_json_error. Nunca use echo direto — sempre encerre com as funções padrão para garantir formatação JSON consistente.

No JavaScript, você precisa do URL do admin-ajax.php e do nonce. Ambos são passados do PHP para o JS via wp_localize_script, que injeta um objeto JavaScript com as variáveis necessárias. Em seguida, faça o POST com fetch ou jQuery, sempre incluindo action e nonce nos parâmetros.

Como usar ajax wordpress de forma performática exige cuidado: cada requisição executa o WordPress completo, carregando todos os plugins e o tema. Em sites com tráfego alto, isso vira gargalo. Combine com um cache de objeto Redis para reduzir o impacto e nunca dispare requisições AJAX em loops sem necessidade.

AJAX vs REST API

O AJAX clássico via admin-ajax.php e a REST API são caminhos diferentes para o mesmo objetivo: comunicar JavaScript e WordPress. A REST API surgiu em 2016 e oferece uma arquitetura mais moderna baseada em endpoints REST padronizados, com URLs do tipo /wp-json/meu-plugin/v1/recurso.

A REST API tem vantagens claras em projetos novos: estrutura previsível, suporte nativo a autenticação por token e por cookie, documentação consistente, integração mais limpa com aplicações headless e SPAs. Permissões via callback dedicada e schema tipado por endpoint deixam o código mais seguro.

O admin-ajax.php ainda manda em três casos: plugins legados que já dependem dele, integrações simples onde criar um endpoint REST seria over-engineering, e cenários onde você precisa do contexto completo do wp-admin com todos os hooks de admin já carregados. Nesses casos, mantém-se a tradição.

Em performance, a diferença é marginal nos dois lados. O que pesa é a quantidade de plugins ativos e a infraestrutura. Sites WordPress que dependem fortemente de AJAX ou REST API se beneficiam de uma stack profissional bem configurada — a FULL Services entrega o conjunto completo com cache de objeto via Redis, OPcache afinado e CDN integrada, garantindo que cada requisição AJAX responda em milissegundos mesmo sob carga.