Como Utilizar o Hook wp_enqueue_scripts para para Adicionar Scripts no WordPress

O hook de ação wp_enqueue_scripts é um componente vital do processo de desenvolvimento de sites na plataforma do WordPress.

Junto das funções wp_enqueue_script() e wp_enqueue_style(), o wp_enqueue_scripts ajuda o WordPress a fazer a exibição ordenada de conteúdos personalizados nas páginas dos sites desenvolvidos com a plataforma.

Neste tutorial, vamos ver como o hook wp_enqueue_scripts funciona em conjunto com outras funções complementares. Além disso, vamos apresentar múltiplos exemplos de casos de uso que podem te ajudar a melhorar as funcionalidades dos seus projetos no WordPress.

O que é a Função “Enqueue” no WordPress

Enqueue ou enqueueing no WordPress se refere ao processo de registrar e adicionar scripts ou folhas de estilo (stylesheets) em um site. A tradução literal do termo “enqueque” para o portguês é “enfileirar”. 

As funções wp_enqueue_script() e wp_enqueue_style() dão instruções ao servidor WordPress para que ele adicione certos scripts e folhas de estilo em uma fila (queue) que faz o carregamento de elementos no front end do site. 

A principal vantagem do enqueueing é que esse processo pode melhorar significativamente o desempenho do site ao reduzir o tempo de carregamento das páginas. Além disso, fazer o enqueue de elementos ajuda a evitar conflitos entre os scripts quando diferentes plugins e temas do WordPress tentam carregar a mesma folha de estilo ou script.

Entendendo o que é o wp_enqueue_script

O processo de enfileirar elementos para carregamento no front end de um site consiste basicamente no hook WordPress wp_enqueue_scripts e de mais duas funções adicionais para stylesheets e scripts.

Vamos começar pelo primeiro elemento, o gancho wp_enqueue_scripts, que é um hook de ação utilizado para adicionar arquivos JavaScript e folhas de estilo à fila de carregamento do seu site. Geralmente, esse hook é utilizado no arquivo functions.php do tema do seu site WordPress ou em diretórios de plugins. 

As funções adicionais wp_register_style() e wp_enqueue_style() são funções básicas do WordPress que funcionam para enfileirar exclusivamente stylesheets. A função de “register” é responsável por registrar a folha de estilo personalizada que será adicionada em um plugin ou no tema do site. Enquanto isso, a função “enqueue” enfileira e faz o carregamento dessa stylesheet no site WordPress.

Por padrão, ambas funções possuem dois parâmetros principais:

• $handle – é o termo a ser substituído pelo nome da stylesheet em questão, que deve ser único. O handle serve para identificar a folha de estilo dentro da base de códigos do WordPress. Para fazer o enqueuing da stylesheet, o nome inserido no parâmetro “handle” deve ser o mesmo que você especificou para fazer o registro da folha de estilo.
• $src – se refere à URL ou ao caminho do arquivo da stylesheet. Esse pode ser o caminho relativo do arquivo da folha de estilo localizada no diretório de um plugin ou tema do WordPress, ou a URL absoluta de uma folha de estilo que está hospedada em outro servidor. O elemento $src é opcional e só precisa ser especificado caso você não tenha indicado a URL ou o caminho do arquivo já na função wp_register_style().

Sendo assim, é possível utilizar a função wp_enqueue_style() sem necessariamente precisar usar a função wp_register_style() antes.

Para ilustrar o caso, abaixo indicamos um exemplo de código que usa as duas funções:

function register_plugin_styles() {

wp_register_style( 'plugin-development', plugins_url( '/css/plugin.css' ) );

wp_enqueue_style( 'plugin-development' );

}

add_action( 'wp_enqueue_scripts', 'register_plugin_styles' );

Agora, vamos conferir um exemplo de código que utiliza apenas a função wp_enqueue_style():

function register_plugin_styles() {

wp_enqueue_style( 'plugin-development', plugins_url( '/css/plugin.css' ) );

}

add_action( 'wp_enqueue_scripts', 'register_plugin_styles' );

Igualmente importantes, as funções WordPress wp_register_script() e wp_enqueue_script() são responsáveis pela ordenação de scripts, e não folhas de estilo. A função “register” faz o registro dos arquivos JavaScript personalizados, já a função wp_enqueue_script() carrega esses scripts personalizados no site. Ambas funções também utilizam os mesmos dois parâmetros principais:

• $handle – é identificador do script, que deve representar um nome único na base de códigos do WordPress. Lembre-se de que você deve utilizar o mesmo nome no handle das duas funções: wp_register_script() e wp_enqueue_script().
• $src – elemento que deve ser substituído pela URL ou pelo caminho que leva ao arquivo de script jQuery. Esse parâmetro é opcional para a função wp_enqueue_script() caso você já tenha especificado a informação da URL na função de registro do script personalizado.

Além dos dois parâmetros básicos, você ainda pode configurar outros três parâmetros nas funções de adicionar scripts personalizados:

• $deps – refere-se a um array (variável ou estrutura de armazenamento) de outros scripts dos quais o atual script personalizado depende. Por exemplo, arquivos jQuery JavaScript ou json2.
• $ver – é o número da atual versão do script personalizado. Trata-se de um parâmetro muito útil caso você possua muitos scripts diferentes e deseja identificar e monitorar as versões deles.
• $in_footer – parâmetro que determina se o script em questão deve ser carregado ou não no rodapé da página. Por padrão, o WordPress carrega scripts na seção <head> (cabeçalho) das páginas do site.

De modo similar à função wp_enqueue_style(), você pode utilizar a função de enfileiramento wp_enqueue_script() sem precisar registrar o script antes através da função específica para isso.

Abaixo ilustramos um exemplo que utiliza ambas funções, de registro e de enfileiramento, para adicionar um script ao site:

function register_plugin_script() {

wp_register_script( 'new-script', plugins_url( '/script.js' ) );

wp_enqueue_script( 'new-script' );

}

add_action( 'wp_enqueue_scripts', 'register_plugin_script' );

Agora, vamos conferir como esse processo pode ser feito sem a função de registro, utilizando somente a função de enqueue: 

function register_plugin_script() {

wp_enqueue_script( 'new-script', plugins_url( '/script.js' ) );

}

add_action( 'wp_enqueue_scripts', 'register_plugin_script' );

Como Usar o Hook wp_enqueue_script no WordPress

Agora que você já conhece os principais aspectos da estrutura e do funcionamento da função wp_enqueue_script(), chegou a hora de saber quando ela pode ser utilizada. Na próxima seção, vamos apresentar alguns casos em que o uso do gancho wp_enqueue_script é bastante popular. Esses exemplos servem para te ajudar a entender melhor o processo de enqueque de scripts personalizados no WordPress.

Como Utilizar o wp_enqueue_script com jQuery

A função wp_enqueue_script() possui um parâmetro adicional denominado array(), que permite que os usuários especifiquem dependências indispensáveis de script.

function my_custom_script() {

    wp_enqueue_script( 'registered-script', get_template_directory_uri() . '/js/meu-script.js', array('jquery'), '1.0', true );

}

add_action( 'wp_enqueue_scripts', 'my_custom_script' );

No código do exemplo acima, utilizamos a função wp_enqueue_scripts() para fazer o enqueue de um script chamado meu-script.js.

Utilizando outros parâmetros disponíveis, ainda especificamos que ele depende da biblioteca jQuery e que deverá ser carregado no rodapé da página. Além disso, também utilizamos a função get_template_directory_uri() para indicar a URL do diretório do tema atual.

Como Carregar Scripts no Rodapé do site com o wp_enqueue_script

Você pode acelerar consideravelmente a velocidade do seu site ao carregar scripts no rodapé (footer) das páginas. Por padrão, o WordPress faz o carregamento dos scripts na seção de cabeçalho do site. Isso quer dizer que eles serão carregados antes de qualquer outro tipo de conteúdo que conste na página. 

Esse recurso pode resultar em tempos de carregamento mais altos para seu site, já que o navegador do visitante fica aguardando esses scripts carregarem.

Agora, se você mover os scripts para a seção de rodapé do site, o navegador de um visitante será capaz de exibir o conteúdo antes e carregar os scripts depois. Confira o exemplo abaixo para entender como esse processo funciona:

function plugin_assets() {

wp_enqueue_script( 'custom-script', plugins_url( '/js/my-script.js' , __FILE__ ), array( 'jquery' ), true );

}

add_action( 'wp_enqueue_scripts', 'plugin_assets' );

Neste código da função wp_enqueue_script(), definimos o parâmetro $in_footer como true (verdadeiro). Assim, o script será enfileirado para carregamento no rodapé e não na seção <head>.

Como Utilizar o wp_enqueue_scripts para Especificar Tipos de Mídia em Stylesheets 

As funções de registrar e enfileirar folhas de estilo, wp_register_style() e wp_enqueue_style(), também contam com um parâmetro adicional. Esse parâmetro é responsável por identificar o tipo de mídia na qual a stylesheet em questão deverá ser aplicada. Por padrão, esse parâmetro de mídia é configurado como all (todos) — o que quer dizer que a stylesheet será aplicada em todos os tipos de mídia.

Para entender melhor essa modificação de função de enqueue, observe o exemplo a seguir:

function my_custom_styles() {

  // Register custom stylesheet

  wp_register_style( 'my-styles', get_template_directory_uri() . '/css/meu-estilo.css', array(), '1.0', 'screen' );

  // Enqueue custom stylesheet

  wp_enqueue_style( 'my-styles' );

}

// Add the hook to the wp_enqueue_scripts action

add_action( 'wp_enqueue_scripts', 'my_custom_styles' );

Neste exemplo, criamos uma função chamada my_custom_styles, que fez o registro e o enqueue de uma stylesheet personalizada chamada meu-estilo.css.

Depois, definimos o parâmetro de tipo de mídia como screen, que quer dizer tela. Isso significa que a folha de estilo em questão será aplicada quando a página for exibida em telas de dispositivos como computadores (desktop), notebooks ou tablets. 

Também é possível utilizar diferentes tipos de mídias, configurando o parâmetro como print para mídias impressas ou handheld para carregamento e exibição em dispositivos móveis e portáteis.

Conclusão

O hook wp_enqueue_scripts e suas funções complementares, como wp_enqueue_script() e wp_enqueue_style(), representam um recurso muito eficiente para adicionar scripts e estilos personalizados no seu site WordPress de forma rápida e prática.

Neste tutorial, te explicamos o que é o processo de enqueueing no WordPress e apresentamos vários exemplos de casos em que você pode utilizar as funções wp_register_script(), wp_register_style(), wp_enqueue_script() e wp_enqueue_style().Esperamos que este guia tenha sido útil para te ajudar a entender melhor o processo de enfileiramento de estilos e scripts no WordPress. Se ainda tiver alguma dúvida, indicamos a leitura do nosso guia WordPress. Também fique à vontade para deixar um comentário na seção disponível abaixo.