WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

zh-cn:功能参考/wp enqueue script

Contents

功能说明

安全地将 javascript 代码加入到 WordPress 创建的页面中。一般来说,将没有被内置的代码进行添加,并在 WordPress 运行时进行加载。

使用方法

wp_enqueue_script( 
     $handle
    ,$src
    ,$deps
    ,$ver
    ,$in_footer 
);

使用 wp_enqueue_scripts 行为来调用本功能, 或者使用 admin_enqueue_scripts 在管理界面进行调用, or use login_enqueue_scripts for login screens. 在行为之外进行调用将会导致问题产生。参见#11526获得详细信息。

参数

$handle
(string) (required) 代码的名称。使用小写字母。
Default: None
$src
(string) (可选项) 代码的 URL 。例如:“http://example.com/wp-includes/js/scriptaculous/scriptaculous.js”。这个参数仅在 WordPress 没有内置该代码时使用。不可使用绝对地址来定位代码,应当使用Function Reference/plugins_url(对应于插件情况)和Function Reference/get_template_directory_uri(对应于模板情况)来获得正确的 URL 。
Default: false
$deps
(array) (可选项) 本代码依赖的代码的名称;需要在本代码之前加载的代码的名称。如果没有依赖关系置为 false 。这个参数仅在 WordPress 没有内置该代码时使用。
Default: array()
$ver
(string) (可选项) 表示代码版本号的字串,将会作为查询字串附加在路径的末尾。默认为 false 。如果没有设置,或者设置为 false ,wordpress 将会自动将 wordpress 的版本号附加在路径的末尾。这个参数用来确保正确的版本信息传递给了客户端,以免受到缓存的影响,因此如果可以获得合适的版本号就应该使用。如果你不愿意附加任何版本号信息在路径的末尾,你就必须将本参数设置为 NULL 。将 NULL 进行传递是不被推荐的,所以使用 NULL 之前请确保 NULL 是可行的。
Default: false
$in_footer
(boolean) (可选项) 一般代码放置于 <head> 部分。如果将这个参数设置为 ture,代码将被放置在 <body> 部分的末尾。这就需要模板要正确的放置wp_footer()勾件。注意你需要将本功能放置在wp_head之前,相应的代码才能被加载,即使设置了将代码放置在页脚处。(WordPress 2.8 新设置)
Default: false

返回值

(void) 
本功能不返回任何值。

举例

注意: 从 wp_head 或者 wp_print_scripts 行为调用本功能会无法运行,因为文件需要在这些功能之前运行。参见[#Usage 使用方法]部分以进行正确的使用。

从非默认位置调用一个默认的 WordPress 代码

Please Note: It is not recommended that a theme force a 3rd party served JavaScript or CSS file by default, Doing so opens the users up to reliance upon a external host which is out of their control. A much better alternative is to use/recomend a Plugin such as Plugin: Use Google Libraries which automatically uses the Google-CDN served jQuery of the same version that WordPress uses this ultimately reduces breakage caused by Themes/Plugins which hardcode the file to use.

Suppose you want to use the CDN copy of jQuery instead of WordPress’s, add this code to your functions.php file.

<?php
function my_scripts_method() {
    wp_deregister_script( 'jquery' );
    wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js');
    wp_enqueue_script( 'jquery' );
}    
 
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>

by using the wp_enqueue_scripts hook (instead of the init hook which many articles reference), we avoid registering the alternate jQuery on admin pages, which will cause post editing (amongst other things) to break after upgrades often.

Load the scriptaculous script

<?php
function my_scripts_method() {
    wp_enqueue_script('scriptaculous');            
}    
 
add_action('wp_enqueue_scripts', 'my_scripts_method'); // For use on the Front end (ie. Theme)
?>

The above example only loads the Scriptaculous library on the front end, If it was needed within the admin, you could use the admin_enqueue_scripts action instead, however this enqueues it on ALL admin pages, which often leads to plugin/core conflicts, ultimately breaking the WordPress admin experience. Instead, You should only load it on the individual pages you need it, See the Load scripts only on Plugin pages section for an example of that.

Load script depends on scriptaculous

Add and load a new script that depends on scriptaculous (this will also cause it to load scriptaculous into the page as well):

<?php
function my_scripts_method() {
   wp_enqueue_script('newscript',
     /* WP_PLUGIN_URL . '/someplugin/js/newscript.js', // old way, not SSL compatible */
     plugins_url('/js/newscript.js', __FILE__), // where the this file is in /someplugin/
     array('scriptaculous'),
     '1.0' );
}    
 
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>

Load a script from your theme which depends upon a WordPress Script

Often JavaScript files included in Themes require another JavaScript file to be loaded before the themes JavaScript file, WordPress offers an API for marking Dependencies when registering a script, For Example, the below theme requires jQuery for the custom_script JavaScript file:

<?php
function my_scripts_method() {
   // register your script location, dependencies and version
   wp_register_script('custom_script',
       get_template_directory_uri() . '/js/custom_script.js',
       array('jquery'),
       '1.0' );
   // enqueue the script
   wp_enqueue_script('custom_script');
}
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>

Load scripts only on plugin pages

<?php
    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_styles-' . $page, 'my_plugin_admin_styles');
    }

    function my_plugin_admin_styles() {
        /*
         * 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 noConflict wrappers

Note: The jQuery library included with WordPress loads in "no conflict" mode. This is to prevent compatibility problems with other javascript libraries that WordPress can load.

In "no-confict" mode, the $ shortcut is not available and the longer jQuery is used. For example:

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

Becomes:

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

In order to use the default jQuery shortcut of $, you can use the following wrapper around your code:

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

That wrapper will cause your code to be executed when the page finishes loading, and the $ will work for calling jQuery. If, for some reason, you want your code to execute immediately (instead of waiting for the DOM ready event), then you can use this wrapper method instead:

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

Default scripts included with WordPress

Script Name Handle
Scriptaculous Root scriptaculous-root
Scriptaculous Builder scriptaculous-builder
Scriptaculous Drag & Drop scriptaculous-dragdrop
Scriptaculous Effects scriptaculous-effects
Scriptaculous Slider scriptaculous-slider
Scriptaculous Sound scriptaculous-sound
Scriptaculous Controls scriptaculous-controls
Scriptaculous scriptaculous
Image Cropper Image cropper (not used in core, see jcrop)
Jcrop Image copper
SWFObject swfobject
SWFUpload swfupload
SWFUpload Degarade swfupload-degrade
SWFUpload Queue swfupload-queue
SWFUpload Handlers swfupload-handlers
jQuery jquery
jQuery Form jquery-form
jQuery Color jquery-color
jQuery UI Core jquery-ui-core (Att.: This is not the whole core incl. all core plugins. Just the base core.)
jQuery UI Tabs jquery-ui-tabs
jQuery UI Sortable jquery-ui-sortable
jQuery UI Draggable jquery-ui-draggable
jQuery UI Droppable jquery-ui-droppable
jQuery UI Selectable jquery-ui-selectable
jQuery UI Resizable jquery-ui-resizable
jQuery UI Dialog jquery-ui-dialog
jQuery Schedule schedule
jQuery Suggest suggest
ThickBox thickbox
jQuery Hotkeys jquery-hotkeys
Simple AJAX Code-Kit sack
QuickTags quicktags
Farbtastic (color picker) farbtastic
ColorPicker (deprecated) colorpicker
Tiny MCE tiny_mce
Prototype Framework prototype
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

Notes

  • See WP_Scripts::add_data(), WP_Scripts::enqueue()
  • Uses global: (unknown type) $wp_scripts
  • jQuery UI Effects is NOT included with the jquery-ui-core

Change Log

Since: 2.6 (BackPress version: r16)

Source File

wp_enqueue_script() is located in wp-includes/functions.wp-scripts.php.

Resources

Related

wp_register_script(), wp_deregister_script(), wp_enqueue_script(), wp_dequeue_script()

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.