🛠 Wp_enqueue_script: como adicionar JavaScript ao tema WordPress corretamente, sem conflitos

Q: Em que difere wp_register_script de wp_enqueue_script?

wp_register_script apenas regista um script no sistema (define handle, caminho, dependências) mas não emite a tag na página. wp_enqueue_script regista E coloca imediatamente na fila para emissão. A separação é útil quando o script nem sempre é necessário: registe uma vez no functions.php, e chame wp_enqueue_script('my-handle') apenas nas páginas necessárias.

Q: O que fazer se os scripts deixarem de funcionar após uma atualização do tema?

Muito provavelmente a atualização sobrescreveu o seu functions.php. A solução é um tema filho: crie um, mova as suas funções para lá e ative-o. Depois disso, as atualizações do tema pai deixarão o seu código intacto.

A sua galeria do WordPress deixou de funcionar após uma atualização. Parece-lhe familiar?

Quase sempre a causa é JavaScript inserido diretamente no header.php, sem hooks, sem dependências, sem ter em conta que um plugin de cache pode alterar a ordem de carregamento. Um plugin carrega o jQuery, outro carrega a sua própria versão do jQuery, e o seu script fica pelo meio e crasha com $ is not defined.

Na prática, uma única chamada wp_enqueue_script no sítio certo é suficiente para esquecer os conflitos para sempre. Segue-se uma análise completa: desde erros de principiante a estratégias de defer/async e opções de ajuste fino que surgiram no WordPress 6.6.

💡 Visão geral rápida:

Não insira tags de script diretamente no header.php ou footer.php: isto cria conflitos com plugins e quebra temas filho
Faça o enqueue do JavaScript através do wp_enqueue_script no functions.php com o hook wp_enqueue_scripts: o WordPress colocará as tags no head ou antes de /body por si
Para código inline curto use wp_add_inline_script, não uma tag de script solta: preserva a ordem de execução e dá aos plugins a oportunidade de intercetar o código
No WordPress 6.3+ especifique uma estratégia defer ou async diretamente nos parâmetros da chamada, e a partir da 6.6, também o fetchpriority
Remova scripts de terceiros através de wp_dequeue_script se um plugin tornar o seu site lento: a prioridade do hook decide

Como o JavaScript é adicionado incorretamente ao WordPress

Cenário típico: precisa de carregar o seu custom.js, e o programador insere esta linha no header.php:

1 <script src="<?php echo get_template_directory_uri(); ?>/js/custom.js"></script>

Parece funcionar. Mas esta abordagem cria três problemas.

Conflitos com plugins. Um plugin de cache combina scripts numa ordem diferente, um plugin de minificação renomeia o ficheiro e quebra o caminho. Se outro plugin já carregou o jQuery e você o carrega novamente, ocorre carregamento duplo e erros na consola.

Impossibilidade de substituir através de um tema filho. Ao usar um tema filho, o header.php raramente é copiado. Se o script estiver codificado diretamente no header.php do tema pai, o tema filho não pode removê-lo ou substituí-lo sem copiar o ficheiro inteiro, e isto significa que as edições serão perdidas quando o tema pai for atualizado.

Sem dependências. O navegador carrega o seu script antes do jQuery, e obtém $ is not defined. O script carrega em todas as páginas, mesmo onde não é necessário, e os pedidos extra tornam o site mais lento.

A forma correta: wp_enqueue_script

O WordPress fornece um sistema de fila para scripts e estilos. Não insere <script> manualmente, em vez disso regista o script através de PHP, especifica dependências e o local de carregamento. O WordPress coloca as tags no <head> ou antes de </body> por si.

Exemplo mínimo funcional para o functions.php do seu tema:

1 /**
2  * Enqueue the main theme script.
3  */
4 function mytheme_enqueue_scripts() {
5     wp_enqueue_script(
6         'mytheme-main',                                     // $handle — unique name
7         get_template_directory_uri() . '/js/main.js',       // $src — file path
8         array( 'jquery' ),                                  // $deps — dependencies
9         '1.0.0',                                            // $ver — version for cache busting
10         true                                                // $in_footer — load in footer
11     );
12 }
13 add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

A função wp_enqueue_script aceita cinco parâmetros. $handle, um identificador único: se outro plugin já registou um script com o mesmo handle, não haverá carregamento duplicado. $deps, um array de handles de dependências: o WordPress carregará os scripts necessários antes do seu. $in_footer com o valor true coloca a tag <script> antes de </body>, o que acelera a renderização da página.

Nota: get_template_directory_uri() aponta para a pasta do tema pai. Num tema filho use get_stylesheet_directory_uri(), o URL apontará para a pasta do filho, e o seu script não se perderá quando o tema pai for atualizado.

Estratégias de carregamento: defer, async e fetchpriority

A partir do WordPress 6.3, o parâmetro $args aceita um array com definições adicionais:

1 wp_enqueue_script(
2     'mytheme-main',
3     get_template_directory_uri() . '/js/main.js',
4     array( 'jquery' ),
5     '1.0.0',
6     array(
7         'in_footer' => true,
8         'strategy'  => 'defer',
9     )
10 );

A estratégia defer diz ao navegador: «carrega o script em paralelo, executa após a construção do DOM». A ordem de execução é garantida, os scripts com defer executam na ordem em que foram adicionados ao DOM. A estratégia async significa «executa assim que for carregado», a ordem não é garantida. Para scripts de tema que dependem do DOM, escolha defer.

A partir do WordPress 6.6, o array $args ganhou mais dois parâmetros. fetchpriority controla a prioridade de carregamento ('high' ou 'low'), útil para scripts críticos que devem carregar antes de outros. module_dependencies aceita um array de IDs de módulos para importação dinâmica, isto é para cenários avançados com módulos ES. Importante: ao especificar module_dependencies o script deve carregar no footer (in_footer => true) ou com a estratégia defer, caso contrário o mapa de importação de módulos não estará pronto quando o script executar.

Que scripts já existem no WordPress

O WordPress regista dezenas de bibliotecas JavaScript de raiz: jQuery, jQuery UI, Backbone, wp-api, MediaElement.js e outras. Lista completa na documentação oficial.

A regra principal: nunca carregue jQuery de uma CDN como a Google ou cdnjs se o seu tema funciona no ecossistema WordPress. O próprio WordPress fornece o jQuery com o handle jquery. Para o usar, basta especificar array( 'jquery' ) nas dependências, o WordPress carregará a sua própria versão testada para compatibilidade com todo o core.

Pode verificar se uma biblioteca está registada através de wp_script_is():

1 if ( wp_script_is( 'jquery-ui-datepicker', 'registered' ) ) {
2     // Library is available — just add to $deps
3 }

Usar o hook wp_enqueue_scripts

O hook wp_enqueue_scripts é acionado no frontend. É nele que as chamadas wp_enqueue_script são envolvidas. Não chame a função diretamente no corpo do functions.php sem um hook, o script pode carregar antes de o WordPress registar as bibliotecas do sistema.

Para a área de administração use um hook separado:

1 add_action( 'admin_enqueue_scripts', 'mytheme_admin_scripts' );
2 function mytheme_admin_scripts( $hook_suffix ) {
3     // $hook_suffix contains the current admin page
4     if ( 'post.php' !== $hook_suffix ) {
5         return; // load script only on the post edit page
6     }
7     wp_enqueue_script( 'mytheme-admin', get_template_directory_uri() . '/js/admin.js', array(), '1.0', true );
8 }

O carregamento condicional poupa recursos: um script para uma página de opções não deve carregar em todas as páginas de administração. O parâmetro $hook_suffix é passado automaticamente pelo WordPress, use-o.

Se um script for necessário tanto no frontend como no admin, prenda uma função a ambos:

1 add_action( 'wp_enqueue_scripts', 'mytheme_global_scripts' );
2 add_action( 'admin_enqueue_scripts', 'mytheme_global_scripts' );

Adicionar JavaScript inline: wp_add_inline_script

Nem todo o código merece um ficheiro separado. Para snippets curtos, contadores, variáveis de configuração, handlers rápidos, o WordPress fornece wp_add_inline_script:

1 function mytheme_inline_config() {
2     wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/js/main.js', array(), '1.0', true );
3     wp_add_inline_script(
4         'mytheme-main',
5         'const MYTHEME_AJAX_URL = "' . admin_url( 'admin-ajax.php' ) . '";',
6         'before'
7     );
8 }
9 add_action( 'wp_enqueue_scripts', 'mytheme_inline_config' );

O terceiro parâmetro, 'before' ou 'after', determina onde o código é inserido em relação ao script especificado. Isto é conveniente para passar variáveis PHP para JavaScript: o URL do handler AJAX, a chave nonce de segurança, o ID do post atual.

Detalhe importante: wp_add_inline_script só funciona com um script registado. Se passar um handle que não está na fila, o código não será emitido. Portanto, primeiro wp_enqueue_script, depois wp_add_inline_script.

Alternativa para temas filho: wp_head e wp_footer

Se estiver a trabalhar num tema filho e não quiser criar um ficheiro separado, pode emitir código diretamente através dos hooks wp_head (no <head>) ou wp_footer (antes de </body>):

1 add_action( 'wp_footer', function() { ?>
2     <script>
3         ( function( $ ) {
4             'use strict';
5             $( function() {
6                 // Your code here — DOM is already ready
7             } );
8         } ( jQuery ) );
9     </script>
10 <?php } );

Este método é mais curto, mas menos flexível do que wp_enqueue_script: sem dependências, versionamento ou capacidade de remover o script através de um tema filho. Use-o para pequenas correções quando não quiser criar um ficheiro separado.

Como remover um script adicionado por um plugin ou tema

Por vezes um plugin carrega um script desnecessário em todas as páginas e torna o site lento. Pode removê-lo através de wp_dequeue_script:

1 function mytheme_dequeue_plugin_scripts() {
2     if ( ! is_page( 'contacts' ) ) {
3         wp_dequeue_script( 'plugin-handle' );
4     }
5 }
6 add_action( 'wp_enqueue_scripts', 'mytheme_dequeue_plugin_scripts', 20 );

A prioridade 20 (terceiro argumento de add_action) coloca a sua função após o registo do plugin, caso contrário o handle ainda não estará na fila. Pode encontrar o handle de um script através da consola do navegador: abra o código fonte da página e encontre o atributo id na tag <script>, o handle geralmente corresponde ao id sem o sufixo -js.

Se precisar de substituir completamente um script, primeiro remova o registo do antigo através de wp_deregister_script, depois registe o novo:

1 function mytheme_replace_script() {
2     wp_deregister_script( 'old-handle' );
3     wp_enqueue_script( 'old-handle', get_template_directory_uri() . '/js/replacement.js', array(), '2.0', true );
4 }
5 add_action( 'wp_enqueue_scripts', 'mytheme_replace_script', 20 );

Antes de tais operações, faça uma cópia de segurança completa do site. Substituir scripts de plugins é um caminho direto para funcionalidades quebradas se não testar num ambiente de staging.

O vídeo acima mostra uma análise passo a passo de como fazer enqueue de CSS e JavaScript num tema WordPress através de wp_enqueue_script e wp_enqueue_style. Se é novo nos hooks, comece por ele, depois volte a este guia escrito para os detalhes.

⁉️🤔 Perguntas frequentes

É obrigatório usar wp_enqueue_script para cada ficheiro js?

Na prática, sim, para todos os scripts carregados globalmente. Para um script que funciona numa única página e é gerado dinamicamente, é aceitável inserir <script> diretamente no template. Mas assim que tiver dois ou mais scripts, a fila através de wp_enqueue_script poupa horas de depuração.

Em que difere wp_register_script de wp_enqueue_script?

wp_register_script apenas regista um script no sistema (define handle, caminho, dependências) mas não emite a tag na página. wp_enqueue_script regista E coloca imediatamente na fila para emissão. A separação é útil quando o script nem sempre é necessário: registe uma vez no functions.php, e chame wp_enqueue_script('my-handle') apenas nas páginas necessárias.

Posso carregar scripts de uma CDN externa?

Tecnicamente, sim, passe o URL completo como segundo parâmetro. Mas para jQuery e outras bibliotecas core do WordPress isto é má prática: o WordPress já as inclui e testa a compatibilidade. Uma CDN externa justifica-se para serviços de terceiros como Google Analytics, reCAPTCHA, widgets de chat. Aí especifique o URL tal como está.

Como verifico que um script foi realmente carregado?

Abra as ferramentas de programador (F12), separador Rede, filtre por JS e atualize a página. O seu ficheiro deve estar na lista com o código de estado 200. Se o script estiver em falta, verifique se o hook wp_enqueue_scripts é acionado nesta página e se o caminho do ficheiro está correto. Para depuração, emita get_template_directory_uri() separadamente e compare o URL.

O que fazer se os scripts deixarem de funcionar após uma atualização do tema?

Muito provavelmente a atualização sobrescreveu o seu functions.php. A solução é um tema filho: crie um, mova as suas funções para lá e ative-o. Depois disso, as atualizações do tema pai deixarão o seu código intacto.

O que significa o erro "$ is not defined" ao usar jQuery?

O WordPress carrega o jQuery em modo noConflict, a variável $ não é ocupada pelo jQuery para evitar conflitos com outras bibliotecas. Use o nome completo jQuery em vez de $ ou envolva o código numa função autoinvocada: (function($) { ... })(jQuery);.

Vale a pena preocupar-se com wp_enqueue_script para meia dúzia de scripts?

Se tiver mais do que um plugin no site, vale a pena. A fila de scripts do WordPress foi concebida porque um plugin a carregar jQuery diretamente quebra metade do site no momento em que instala um plugin de cache. wp_enqueue_script elimina toda esta classe de problemas.

Para um tema de cinco ficheiros, use wp_enqueue_script. Para um snippet curto numa página específica, wp_add_inline_script ou o hook wp_footer servem. Mas assim que tiver dois ou mais scripts, volte à fila. Uma hora gasta em enqueuing correto agora poupa uma noite de depuração após a próxima atualização do WordPress.

1	/**
2	* Enqueue the main theme script.
3	*/
4	function mytheme_enqueue_scripts() {
5	wp_enqueue_script(
6	'mytheme-main', // $handle — unique name
7	get_template_directory_uri() . '/js/main.js', // $src — file path
8	array( 'jquery' ), // $deps — dependencies
9	'1.0.0', // $ver — version for cache busting
10	true // $in_footer — load in footer
11	);
12	}
13	add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

1	wp_enqueue_script(
2	'mytheme-main',
3	get_template_directory_uri() . '/js/main.js',
4	array( 'jquery' ),
5	'1.0.0',
6	array(
7	'in_footer' => true,
8	'strategy' => 'defer',
9	)
10	);

1	if ( wp_script_is( 'jquery-ui-datepicker', 'registered' ) ) {
2	// Library is available — just add to $deps
3	}

1	add_action( 'admin_enqueue_scripts', 'mytheme_admin_scripts' );
2	function mytheme_admin_scripts( $hook_suffix ) {
3	// $hook_suffix contains the current admin page
4	if ( 'post.php' !== $hook_suffix ) {
5	return; // load script only on the post edit page
6	}
7	wp_enqueue_script( 'mytheme-admin', get_template_directory_uri() . '/js/admin.js', array(), '1.0', true );
8	}

1	function mytheme_inline_config() {
2	wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/js/main.js', array(), '1.0', true );
3	wp_add_inline_script(
4	'mytheme-main',
5	'const MYTHEME_AJAX_URL = "' . admin_url( 'admin-ajax.php' ) . '";',
6	'before'
7	);
8	}
9	add_action( 'wp_enqueue_scripts', 'mytheme_inline_config' );

1	add_action( 'wp_footer', function() { ?>
2	<script>
3	( function( $ ) {
4	'use strict';
5	$( function() {
6	// Your code here — DOM is already ready
7	} );
8	} ( jQuery ) );
9	</script>
10	<?php } );

1	function mytheme_dequeue_plugin_scripts() {
2	if ( ! is_page( 'contacts' ) ) {
3	wp_dequeue_script( 'plugin-handle' );
4	}
5	}
6	add_action( 'wp_enqueue_scripts', 'mytheme_dequeue_plugin_scripts', 20 );

1	function mytheme_replace_script() {
2	wp_deregister_script( 'old-handle' );
3	wp_enqueue_script( 'old-handle', get_template_directory_uri() . '/js/replacement.js', array(), '2.0', true );
4	}
5	add_action( 'wp_enqueue_scripts', 'mytheme_replace_script', 20 );

Tudo para WordPress, desenvolvimento web — e não só

🛠 Inclusão correta de JavaScript em temas WordPress