WordPress 加载 JS 函数:wp_enqueue_script()

函数说明

使用 wp_enqueue_script() 函数安全的将 JavaScript 脚本添加到 WordPress 生成的页面。 wp_enqueue_script() 函数会加载未被加载的脚本，并安全的处理依赖关系。

函数用法

<?php wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ); ?>

使用 wp_enqueue_scripts 动作调用 wp_enqueue_script() 函数，或者使用 admin_enqueue_scripts 动作在管理页面调用 wp_enqueue_script() 函数，或者使 login_enqueue_scripts 动作在登录页面调用 wp_enqueue_script() 函数。

参数说明

$handle
(string) (required) 脚本名称，使用小写字母。
Default: None

$src
(string) (optional) 脚本的链接。例如：」http://example.com/wp-includes/js/scriptaculous/scriptaculous.js」。 $src 参数仅在 WordPress 没有内置当前时是必填项，$src 参数是必填项。你不需要写死脚本链接，针对插件使用 plugins_url() 函数，针对主题使用 get_template_directory_uri() 函数获取正确的链接。
Default: false

$deps
(array) (optional) 当前脚本依赖的脚本数组（必须在当前脚本之前加载）。如果没有依赖关系则 $deps 参数失效。 $deps 参数仅在 WordPress 没有内置当前脚本时是必填项。
Default: array()

$ver
(string) (optional) 指定脚本版本号的字符串，如果设置 $ver 参数，WordPress 会自动把 $ver 参数作为查询字符串连接到路径末尾。默认为 false 。如果 $ver 参数没有设置或者设置为 false，WordPress 会自动把当前 WordPress 的版本号连接到路径末尾。如果 $ver 参数设置为 null 则不添加版本信息。 $ver 参数用于确保传递给客户端的正确版本不受缓存影响，因此让脚本附加版本号是有道理的。

$in_footer
(boolean) (optional) 通常脚本位于

区域。如果 $in_footer 参数设置为 true，脚本会位于底部。 $in_footer 参数需要主题在适当的位置有 wp_footer() 钩子。请注意，您必须在 wp_head 运行之前加载当前脚本，即使脚本放置在页脚。
Default: false

返回值

(void) wp_enqueue_script() 函数无返回值。

实例

请注意：如果使用 wp_head 或 wp_print_scripts 动作钩子调用 wp_enqueue_script() 函数，则 wp_enqueue_script() 函数不会运行，js 脚本需要在这些动作钩子运行前载入。参考上面的用法章节正确使用钩子。

从一个非 WordPress 默认位置加载默认 WordPress 脚本
请注意：不推荐主题强制默认使用第三方提供服务的 JavaScript 或 CSS 文件，这么做会让用户依赖于一个不受用户控制的外部主机。一个更好的选择是使用/推荐一个插件，例如：Use Google Libraries 插件，此插件自动使用 Google-CDN 提供的和 WordPress 同一版本的 jQuery，最终降低又主题或插件中写死文件造成的破坏风险。

警告：在插件中使用卸载 WordPress 内置的脚本的方法将被拒绝执行。

假设你要使用 CDN 的 jQuery 版本替换 WordPress 内置版本，将如下代码添加到 functions.php 文件。

function my_scripts_method() {
	wp_deregister_script( 'jquery' );
	wp_register_script( 'jquery', 'http://googleajax.admincdn.com/ajax/libs/jquery/1.7.2/jquery.min.js');
	wp_enqueue_script( 'jquery' );
}

add_action('wp_enqueue_scripts', 'my_scripts_method');

通过使用 wp_enqueue_scripts 钩子（替代许多文章引用的 init 钩子）避免在管理页面注册 jQuery 脚本，这将导致在经常升级后编辑文章中断。

加载 scriptaculous 脚本

function my_scripts_method() {
        wp_enqueue_script('scriptaculous');
}

add_action('wp_enqueue_scripts', 'my_scripts_method');

上述代码只在前端页面加载 Scriptaculous 脚本库，如果你需要在管理页面加载，可以使用 admin_enqueue_scripts 动作钩子调用，但是脚本会在所有管理页面载入，这样往往会导致插件/核心冲突，最终破坏 WordPress 的管理体验。相反，你应该只在你需要的单独页面加载脚本，参考只在插件的页面部分加载脚本的例子。

加载依赖于 Scriptaculous 的脚本
加载一个依赖于 Scriptaculous 的新脚本。这将导致 WordPress 在加载当前脚本前先将 Scriptaculous 脚本加载到页面。

function my_scripts_method() {
	wp_enqueue_script(
	'newscript',
	plugins_url('/js/newscript.js', __FILE__),
	array('scriptaculous')
	);
}

add_action('wp_enqueue_scripts', 'my_scripts_method');

从取决于一个 WordPress 脚本的主题加载脚本
主题中的 JavaScript 脚本在加载前通常需要加载其他 JavaScript 脚本。 WordPress 提供了一个在注册脚本时标记依赖关系的 API 。例如，下面的主题中的 custom_script JavaScript 脚本需要先加载 jQuery 脚本：

function my_scripts_method() {
	wp_enqueue_script(
	'custom-script',
	get_template_directory_uri() . '/js/custom_script.js',
	array('jquery')
	);
}
add_action('wp_enqueue_scripts', 'my_scripts_method');

仅在插件页面加载脚本

add_action( 'admin_init', 'my_plugin_admin_init' );
add_action( 'admin_menu', 'my_plugin_admin_menu' );

function my_plugin_admin_init() {
	/* Register our script. */
	wp_register_script( 'my-plugin-script', plugins_url('/script.js', __FILE__) );
}

function my_plugin_admin_menu() {
	/* Register our plugin page */
	$page = add_submenu_page( 'edit.php', // The parent page of this menu
	__( 'My Plugin', 'myPlugin' ), // The Menu Title
	__( 'My Plugin', 'myPlugin' ), // The Page title
	'manage_options', // The capability required for access to this item
	'my_plugin-options', // the slug to use for the page in the URL
	'my_plugin_manage_menu' // The function to call to render the page
	);

	/* Using registered $page handle to hook script load */
	add_action('admin_print_scripts-' . $page, 'my_plugin_admin_scripts');
}

function my_plugin_admin_scripts() {
	/*
	* It will be called only on your plugin admin page, enqueue our script here
	*/
	wp_enqueue_script( 'my-plugin-script' );
}

function my_plugin_manage_menu() {
	/* Output our admin page */
}

jQuery 无冲突模式封装
请注意：WordPress 内置 jQuery 脚本库加载使用无冲突模式，这是为了防止与其他 WordPress 可以加载的 JavaScript 库的兼容性问题。

无冲突模式下，$() 函数无效，使用 jQuery() 函数。例如：

$(document).ready(function(){
	$(#somefunction) ...
});

变成:

jQuery(document).ready(function(){
	jQuery(#somefunction) ...
});

为了使用 jQuery 默认的 shortcut $，你可以使用如下封装代码：

jQuery(document).ready(function($) {
	// $() will work as an alias for jQuery() inside of this function
});

上述封装将导致你的代码在页面加载完成后执行。 $会调用 jQuery 。如果你想让代码立即执行，你可以使用下面的封装方法：

(function($) {
	// $() will work as an alias for jQuery() inside of this function
})(jQuery);

源文件

wp_enqueue_script() 位于 wp-includes/functions.wp-scripts.php

WordPress 加载 JS 函数:wp_enqueue_script()