WordPress函数 / Function Reference / wp_enqueue_script


描述


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


用法



1

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) 通常脚本位于<head>区域。如果$in_footer参数设置为true，脚本会位于<body>底部。$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文件。



WordPress函数：wp_enqueue_script

function my_scripts_method() {

wp_deregister_script( 'jquery' );

wp_register_script( 'jquery', 'http://ajax.googleapis.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'); // For use on the Front end (ie. Theme)

上述代码只在前端页面加载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()函数。例如：



1

2

3

$(document).ready(function(){

$(#somefunction) ...

});

变成:



1

2

3

jQuery(document).ready(function(){

jQuery(#somefunction) ...

});

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



1

2

3

jQuery(document).ready(function($) {

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

});

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



1

2

3

(function($) {

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

})(jQuery);

WordPress内置脚本


Script Name Handle 所需依赖 *

Image Cropper Image cropper (not used in core, see jcrop)

Jcrop Image copper

SWFObject swfobject

SWFUpload swfupload

SWFUpload Degrade swfupload-degrade

SWFUpload Queue swfupload-queue

SWFUpload Handlers swfupload-handlers

jQuery jquery json2 (for AJAX calls)

jQuery Form jquery-form jquery

jQuery Color jquery-color jquery

jQuery UI Core jquery-ui-core (Just the base core.) jquery

jQuery UI Widget jquery-ui-widget jquery

jQuery UI Mouse jquery-ui-mouse jquery

jQuery UI Accordion jquery-ui-accordion jquery

jQuery UI Autocomplete jquery-ui-autocomplete jquery

jQuery UI Slider jquery-ui-slider jquery

jQuery UI Tabs jquery-ui-tabs jquery

jQuery UI Sortable jquery-ui-sortable jquery

jQuery UI Draggable jquery-ui-draggable jquery

jQuery UI Droppable jquery-ui-droppable jquery

jQuery UI Selectable jquery-ui-selectable jquery

jQuery UI Datepicker jquery-ui-datepicker jquery

jQuery UI Resizable jquery-ui-resizable jquery

jQuery UI Dialog jquery-ui-dialog jquery

jQuery UI Button jquery-ui-button jquery

jQuery Schedule schedule jquery

jQuery Suggest suggest jquery

ThickBox thickbox

jQuery Hotkeys jquery-hotkeys jquery

Simple AJAX Code-Kit sack

QuickTags quicktags

Farbtastic (color picker) farbtastic jquery

ColorPicker (deprecated) colorpicker jquery

Tiny MCE tiny_mce

Autosave autosave

WordPress AJAX Response wp-ajax-response

List Manipulation wp-lists

WP Common common

WP Editor editor

WP Editor Functions editor-functions

AJAX Cat ajaxcat

Admin Categories admin-categories

Admin Tags admin-tags

Admin custom fields admin-custom-fields

Password Strength Meter password-strength-meter

Admin Comments admin-comments

Admin Users admin-users

Admin Forms admin-forms

XFN xfn

Upload upload

PostBox postbox

Slug slug

Post post

Page page

Link link

Comment comment

Threaded Comments comment-repy

Admin Gallery admin-gallery

Media Upload media-upload

Admin widgets admin-widgets

Word Count word-count

Theme Preview theme-preview

JSON for JS json2

Plupload plupload

 备注


参考 WP_Scripts::add_data(), WP_Scripts::enqueue()

使用全局变量：(unknown type) $wp_scripts

jQuery UI Effects 不包括在 jquery-ui-core

从 WordPress 3.3 起，wp_enqueue_script()函数可以在页面中被调用（在HTML body内）。这样会在页面底部加载脚本。


更改日志


Since: 2.6 (BackPress version: r16)


源文件


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