Codex tools: Log in
Languages: English • Español • Русский • 中文(简体) • (Add your language)
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获得详细信息。
wp_head之前，相应的代码才能被加载，即使设置了将代码放置在页脚处。(WordPress 2.8 新设置)
注意: 从 wp_head 或者 wp_print_scripts 行为调用本功能会无法运行，因为文件需要在这些功能之前运行。参见[#Usage 使用方法]部分以进行正确的使用。
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.
<?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.
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');
?>
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');
?>
<?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 */
}
?>
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);
| 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 |
Since: 2.6 (BackPress version: r16)
wp_enqueue_script() is located in wp-includes/functions.wp-scripts.php.
wp_register_script(), wp_deregister_script(), wp_enqueue_script(), wp_dequeue_script()
