👉 Como corrigir '$ is not a function' no WordPress: 4 formas
Edita o functions.php, adicionas um par de linhas de jQuery e o site vai abaixo com um ecrã branco. A consola mostra: Uncaught TypeError: $ is not a function. Parece-te familiar?
Qualquer programador de WordPress encontra este erro pelo menos uma vez. Copias código jQuery funcional do CodePen ou de um snippet, colas no teu site e o WordPress não o entende. A razão não é código partido nem conflitos de plugins. A razão é a forma como o WordPress gere o jQuery.
Vamos ver quatro métodos comprovados para corrigir o erro "$ is not a function", desde o seguro wrapper IIFE até desativar completamente o noConflict. Cada método inclui código pronto a usar que podes copiar e colar.
💡 Visão geral rápida:
- Envolver o código jQuery numa função anónima IIFE, o método mais seguro e universal
- Usar o jQuery document ready com um parâmetro dollar para scripts no head
- Atribuir o teu próprio alias via noConflict, conveniente quando o sinal de dólar está a ser usado por outra biblioteca
- Desativar globalmente o noConflict, apenas quando não existem outras bibliotecas no site
Porque é que o erro "$ is not a function" ocorre no WordPress
O WordPress carrega o jQuery em modo noConflict. Isto significa que a variável $, o alias curto do jQuery, não está disponível globalmente. Os programadores do núcleo do WordPress fizeram-no intencionalmente para evitar conflitos: muitas bibliotecas JavaScript (Prototype, MooTools, versões antigas do Bootstrap) também usam $ como o seu atalho principal.
Quando escreves no teu script:
1 $("#element").hide();
O WordPress não sabe que $ é o jQuery. Vê uma chamada a uma função desconhecida e lança TypeError: $ is not a function. Fora do WordPress, numa página HTML simples, este mesmo código funcionaria sem problemas, porque aí o jQuery regista $ globalmente.
Tecnicamente, o WordPress só entende o nome completo: jQuery("#element").hide(). Mas escrever jQuery em vez de $ em cada linha de um script com várias linhas é inconveniente, o código fica inchado e perde legibilidade. Felizmente, há quatro formas de contornar esta limitação.
Antes de editares quaisquer ficheiros do tema, faz uma cópia de segurança do teu site. Um ponto e vírgula a menos no functions.php e o site vai abaixo. Com uma cópia de segurança, podes reverter as alterações num minuto.
Método 1: Wrapper IIFE, seguro e universal
A forma mais fiável de recuperar o $ nos scripts do WordPress é uma Immediately Invoked Function Expression (IIFE). Passas o jQuery como argumento e, dentro da função, referes-te a ele através do familiar $.
Código para o footer.php ou inserção de baixo nível (rodapé do site):
1 (function($) { 2 // Your jQuery code here 3 $("#element").hide(); 4 })(jQuery);
O que acontece aqui: uma função anónima aceita o parâmetro $ e é imediatamente invocada com o argumento jQuery. Dentro desta função $ === jQuery, enquanto fora o $ permanece indefinido. O conflito com outras bibliotecas fica eliminado.
Este método funciona para scripts no rodapé. Se o script tiver de ser executado no <head>, usa o método 2.
Método 2: jQuery(document).ready com parâmetro $
Quando um script tem de ser executado no cabeçalho da página (antes de o DOM carregar), envolve-o em jQuery(document).ready. Nota: o $ é passado para o parâmetro da callback, isto não é um erro de digitação, é um ponto-chave.
Código para o header.php ou functions.php via wp_enqueue_script:
1 jQuery(document).ready(function($) { 2 // Your jQuery code here 3 console.log($); 4 });
O método .ready() espera que o DOM carregue completamente e o jQuery passa-se a si próprio à callback como $. Dentro desta callback, o $ volta a funcionar como num ambiente JavaScript normal. E, ao contrário do método 1, o script arranca a partir do <head>, o que é útil para operações críticas de inicialização.
A maioria dos programadores de temas e plugins conhece esta peculiaridade do WordPress, por isso em produtos de qualidade quase sempre verás jQuery em vez de $, ou um dos wrappers acima.
Método 3: Cria o teu próprio alias via noConflict
O jQuery permite-te não só recuperar o $, mas também atribuir qualquer outro alias curto, por exemplo as variáveis $j ou jq, ou qualquer variável que prefiras. Isto é conveniente quando o site já usa outra biblioteca que ocupou o $.
1 var jq = jQuery.noConflict(); 2 jq("div p").hide(); 3 4 // Another library continues using its own $ 5 $("content").style.display = "none";
O método jQuery.noConflict() liberta o $ para outras bibliotecas e devolve o jQuery à tua variável (jq no exemplo). Depois disto, as chamadas são feitas via jq(...), enquanto o $ funciona para a biblioteca vizinha, o conflito desaparece completamente.
Esta abordagem é especialmente útil em sites onde um tema WordPress coexiste com uma framework JavaScript de terceiros que usa $ para os seus próprios fins.
Método 4: Desativar completamente o noConflict (usar com cautela)
Se souberes com certeza que o site não tem outras bibliotecas a reivindicar o $, podes desativar o modo noConflict globalmente:
1 $ = jQuery.noConflict(true);
Depois desta linha, o $ volta a funcionar como um alias global do jQuery em todo o lado, em qualquer script, em qualquer parte da página. No entanto, este método é o mais arriscado. Se mais tarde instalares um plugin que também use $, o site vai partir com um bug difícil de reproduzir.
Recomendamos os métodos 1 e 2 como principais, são seguros, isolados e cobrem a grande maioria dos cenários reais. O método 4 é para situações em que manténs um script legado grande e não podes envolver cada função separadamente.
No vídeo acima, uma demonstração visual dos quatro métodos em ação. Vê-o se preferires a explicação visual ao texto.
⁉️🤔 Perguntas frequentes
Porque é que o WordPress desativou o $ para o jQuery em primeiro lugar?
Os programadores do núcleo do WordPress ativaram o
jQuery.noConflict()por defeito para proteger os sites de conflitos com outras bibliotecas JavaScript. O Prototype.js, MooTools e algumas frameworks mais antigas também registam uma variável global$. Se o WordPress desse o$ao jQuery, qualquer tema ou plugin com uma dessas bibliotecas partiria o painel de administração ou o frontend. O WordPress corre o jQuery em modo noConflict desde a versão 3.6, isto não é um bug, mas uma decisão de arquitetura. A variável$no escopo global permanece livre para bibliotecas de terceiros. É exatamente por isso que$("#id")fora de um wrapper lançará sempreTypeError.
Posso simplesmente incluir o jQuery uma segunda vez, fora do WordPress?
Tecnicamente, sim, podes incluir o jQuery através de um link CDN uma segunda vez, e ele registará o
$globalmente. Mas isto é uma má prática: duas versões do jQuery na mesma página entram em conflito, o tamanho da página aumenta e os plugins do WordPress esperam exatamente a versão do jQuery registada viawp_enqueue_script. Trabalha sempre com a versão do jQuery que o WordPress fornece, está testada para compatibilidade com o núcleo e o painel de administração. Incluir o jQuery novamente significa criar novos problemas em vez de resolver o original.
O que fazer se o erro aparecer apenas em páginas específicas?
Verifica se a página específica carrega um script de terceiros através de um plugin ou widget. Alguns plugins de caching e minificação reordenam os scripts de forma agressiva e o jQuery pode carregar depois do teu código. Desativa os plugins de otimização um a um para encontrares o culpado. Na maioria dos casos, o problema do "$ is not a function numa só página" é causado pela ordem de carregamento dos scripts. Um plugin de minificação ou caching coloca o teu script antes do jQuery e o
$ainda não existe no momento da chamada. Solução: ou excluis o script da minificação, ou envolve-lo no IIFE do método 1, que não depende do$global.
Existe algum plugin pronto que corrija este erro?
Não existe um plugin dedicado "para corrigir o $ is not a function", e não é necessário. O problema resolve-se com um wrapper de uma linha, e instalar um plugin separado para isto é excessivo. No entanto, existem plugins como o Code Snippets que te permitem adicionar código JavaScript e PHP sem editar ficheiros do tema, o que é mais seguro para principiantes. O Code Snippets guarda o teu código na base de dados, não no
functions.php. Se cometeres um erro de sintaxe, o plugin reverte automaticamente as alterações e o site não vai abaixo. Recomendamos que os principiantes adicionem qualquer código JS através dele, e não editando ficheiros do tema.
O erro "$ is not a function" está corrigido, e agora?
Principal conclusão: o problema não está no teu código nem no WordPress. Este é um comportamento padrão do CMS e corrige-se com um wrapper. Na grande maioria dos casos, o método 1 (IIFE) ou o método 2 (.ready() com $) são suficientes. Não partem outros scripts e funcionam em qualquer versão do WordPress, da 4.0 à mais recente.
Se trabalhas frequentemente com jQuery no WordPress, desenvolve o hábito de começar cada script com (function($) { e terminar com })(jQuery);, isto tornar-se-á memória muscular numa semana e eliminará o erro para sempre.
Partilha o artigo com colegas que ainda editam o functions.php por tentativa e erro, um wrapper pronto a usar poupar-lhes-á uma hora de depuração.
Uma equipa profissional de escritores e editores especializados na criação de conteúdo de qualidade.