O WordPress oferece vários métodos para adicionar estilos e scripts para frontend e admin, tanto para adicionar arquivos quanto para gerar variáveis/saídas diretas. Este post entra em detalhes com exemplos de código de como adicionar scripts e estilos ao WordPress da maneira correta.
Scripts e estilos podem ser registrados e enfileirados definindo identificadores exclusivos (IDs semelhantes a slugs), possibilitando que o WordPress elimine duplicatas, como várias bibliotecas jQuery, e lide com dependências (qual estilo ou script carregar antes disso e daquilo) .
Se não houver necessidade específica de registrar estilos ou scripts, você pode simplesmente enfileirar-los imediatamente, pulando o registro. Também é possível cancelar o registro ou desenfileirar estilos e scripts (wp_dequeue_scripte wp_dequeue_style) consultando o identificador. Geralmente ajuda a adicionar um número maior na prioridade do gancho (fazendo com que ele seja executado após o gancho onde os itens foram enfileirados).
PS: A adição de estilos e scripts ao Gutenberg (blocos de administração e frontend), é explicado no meu post Gutenberg: The Basics.
Adicionando scripts e estilos ao frontend
Para adicionar estilos e scripts apenas ao frontend, use o hook wp_enqueue_scripts. Apesar do nome do gancho, ele é usado tanto para scripts quanto para estilos. Aqui está um exemplo de enfileiramento de uma folha de estilo e um arquivo javascript em um tema:
add_action('wp_enqueue_scripts', function() {
// Styles
wp_enqueue_style('main-style', get_stylesheet_directory_uri().'/style.css', [], '1.0');
// Scripts
wp_enqueue_script('main-script', get_stylesheet_directory_uri().'/assets/js/main.js', ['jquery'], '', true);
});O terceiro argumento para estilos e scripts é um array com dependências. Por exemplo, para scripts, você pode querer carregar a biblioteca jQuery antes do arquivo de script. Nota: As instalações do WordPress vêm com várias bibliotecas de script comuns incluídas (por exemplo, jQuery, jQuery UI, Backbone e Underscore). Contanto que você adicione qualquer um desses identificadores como dependência em seu enqueue_script, o WordPress os enfileirará, para que você não precise adicionar seus próprios arquivos para essas bibliotecas.
O quinto argumento para scripts é se o script deve ou não ser carregado no final de <body>(no rodapé), em vez de dentro da <head>tag.
Para uso em um plugin, você precisa usar outros métodos para obter a URL de um arquivo local, por exemplo plugin_dir_url(__FILE__).
Adicionando scripts e estilos ao administrador
O WordPress oferece outro gancho, admin_enqueue_scripts, para adicionar estilos e scripts apenas ao administrador. Use os mesmos métodos acima para registrar, enfileirar e localizar scripts e estilos:
add_action('admin_enqueue_scripts', function() {
global $pagenow, $post_type;
// Example: $hook == 'edit.php'
// Example: $post_type == 'post'
// wp_enqueue_style or wp_enqueue_script
});Adicionando scripts e estilos à página de login
Como nenhum dos ganchos acima aparece na tela de login do administrador, o WordPress oferece um gancho separado para essa finalidade, login_enqueue_scripts.
add_action('login_enqueue_scripts', function() {
// wp_enqueue_style or wp_enqueue_script
});Como gerar variáveis Javascript
Para gerar variáveis Javascript (por exemplo, obter caminhos, strings traduzidas ou outras variáveis, você pode usar wp_localize_script. Esta função requer um identificador de script enfileirado. O segundo parâmetro seria o nome da variável e o terceiro seu valor. O valor pode ser um array, assim :
add_action('wp_enqueue_scripts', function() {
// wp_enqueue_script('main-script'); // Must exist!
$variable_to_js = [
'ajax_url' => admin_url('admin-ajax.php')
];
wp_localize_script('main-script', 'Theme_Variables', $variable_to_js);
});Dentro do seu script você tem acesso às variáveis passadas, assim:
jQuery(document).ready(function($) {
console.log(Theme_Variables.ajax_url);
});Neste gancho você pode acessar variáveis globais $pagenowe $post_typeespecificar onde deseja enfileirar seus estilos e scripts.
Saída de estilos embutidos
Se você precisar produzir estilos embutidos, por exemplo, para variáveis de tema que você configurou no Personalizador (por exemplo, usando get_theme_mod), você pode produzir esses estilos usando a wp_add_inline_stylefunção. Ele funciona de maneira bastante semelhante à saída de variáveis Javascript, nas quais você precisa fornecer um identificador de estilo enfileirado:
add_action('wp_enqueue_scripts', function() {
// wp_enqueue_style('main-style'); // Must exist!
$color = get_theme_mod('my-custom-color'); // e.g. #FF0000
$custom_css = "
body {
background: {$color};
}";
wp_add_inline_style('main-style', $custom_css);
});Infelizmente, não há função direta ou filtro para adicionar asyncàs suas tags de script, mas podemos conseguir isso manipulando a string que o WordPress usa para gerar as tags de script para todos os scripts enfileirados, assim (lembre-se de especificar seu script por seu identificador):
add_filter('script_loader_tag', function($tag, $handle, $src) {
if ('main-script' != $handle) {
return $tag;
}
return str_replace('<script', '<script async', $tag);
}, 11, 3);Links úteis de documentação
- wp_enqueue_scripts (gancho)
- admin_enqueue_scripts (gancho)
- login_enqueue_scripts (gancho)
- wp_enqueue_style
- wp_dequeue_style
- wp_enqueue_script
- wp_dequeue_script
- wp_localize_script
- wp_add_inline_style