云策 WordPress 开发者社区

钩子文档

wp_enqueue_scripts

查看官方原文 ↗
💡 云策文档标注

概述

wp_enqueue_scripts 是一个 WordPress 动作钩子，用于在前端页面中正确排队加载脚本和样式。尽管名称中包含“scripts”，但它同时适用于脚本和样式。

关键要点

  • wp_enqueue_scripts 是前端脚本和样式排队的标准钩子，应优先使用。
  • 对于管理页面，应使用 admin_enqueue_scripts；对于登录页面，应使用 login_enqueue_scripts。
  • 注意 do_blocks() 在 wp_enqueue_scripts 之前调用，可能导致脚本注册问题，需条件检查。

代码示例

function wpdocs_theme_name_scripts() {
    wp_enqueue_style( 'style-name', get_stylesheet_uri() );
    wp_enqueue_script( 'script-name', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'wpdocs_theme_name_scripts' );

注意事项

  • wp_enqueue_scripts 钩子不传递 $hook 参数，这与 admin_enqueue_scripts 不同。
  • 在内容触发（如短码）中排队脚本时，需确保脚本已注册，避免因 do_blocks() 调用顺序导致的错误。
📄 原文内容

Fires when scripts and styles are enqueued.

More Information

wp_enqueue_scripts is the proper hook to use when enqueuing scripts and styles that are meant to appear on the front end. Despite the name, it is used for enqueuing both scripts and styles.

Usage

function themeslug_enqueue_style() {
    wp_enqueue_style( 'my-theme', 'style.css', false );
}

function themeslug_enqueue_script() {
    wp_enqueue_script( 'my-js', 'filename.js', false );
}

add_action( 'wp_enqueue_scripts', 'themeslug_enqueue_style' );
add_action( 'wp_enqueue_scripts', 'themeslug_enqueue_script' );

Source

do_action( 'wp_enqueue_scripts' );

View all references View on Trac View on GitHub

Used by Description
wp_enqueue_scripts()wp-includes/script-loader.php

Wrapper for do_action( ‘wp_enqueue_scripts’ ).

Changelog

Version Description
2.8.0 Introduced.

User Contributed Notes

  1. Skip to note 7 content


    Drew Jaynes


    You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note

    Basic Example

    /**
 * Proper way to enqueue scripts and styles.
 */
function wpdocs_theme_name_scripts() {
    wp_enqueue_style( 'style-name', get_stylesheet_uri() );
    wp_enqueue_script( 'script-name', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'wpdocs_theme_name_scripts' );

  3. Skip to note 9 content


    thejaydip


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    If you want to add dynamic inline styles.

    function wpdocs_enqueue_custom_style() {
	$theme = wp_get_theme();

	wp_register_style(
		'wpdocs-style',
		get_theme_file_uri( 'css/style.css' ),
		array(),
		$theme->get( 'Version' ),
	);

	wp_enqueue_style( 'wpdocs-style' );


	$custom_css = ".navbar-nav ul li { list-style: none; }";
	wp_add_inline_style( 'wpdocs-style', $custom_css );

}

add_action( 'wp_enqueue_scripts', 'wpdocs_enqueue_custom_style' );

  4. Skip to note 10 content


    Chigozie Orunta


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Selectively load JS files into specific pages like so:

    function wpdocs_selective_js_loading() {
	if ( is_page( ['home', 'about', 'contact'] ) ) {
		wp_enqueue_script( 'your-script', get_template_directory_uri() . '/js/your-script.js', array(), '1.0.0', true );
	}
}
add_action( 'wp_enqueue_scripts', 'wpdocs_selective_js_loading' );

  5. Skip to note 11 content


    tripflex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    do_blocks() is called before wp_enqueue_scripts so if you are correctly registering scripts and only enqueuing on pages it’s needed on (which most developers do not seem to do), keep in mind that if you use something like wp_localize_script, it will not work if you’re registering your script in wp_enqueue_scripts hook and enqueueing it from some kind of trigger generated by content, shortcode, template files, or something else that could be loaded by do_blocks.

    This will result in javascript errors saying XYZ variable is not defined

    I had a lot of plugin clients report issues because of this, as my call to wp_enqueue_script is normally triggered by a template file or something that now gets loaded in do_blocks() (like a shortcode), which is BEFORE wp_enqueue_scripts action is triggered, meaning the script is not registered yet.

    The solution for me in this situation was to create a conditional check before calling wp_localize_script and then wp_enqueue_script, to see if the script has been registered already, and if not, make sure to call wp_register_script first.

  6. Skip to note 12 content


    abdessamad idrissi


    You must log in to vote on the helpfulness of this noteVote results for this note: -19You must log in to vote on the helpfulness of this note

    This actions passes an argument $hook that is handy when for example to prevent the script from loading on certain pages;

    function wpdocs_enqueue_scripts( $hook ) {
	// Load only in add new post page
	if ( is_admin() && 'post-new.php' !== $hook ) {
		return;
	}

	// rest of your code here..
}
add_action( 'wp_enqueue_scripts', 'wpdocs_enqueue_scripts' );