WordPress.org

Ready to get started?Download WordPress

Codex

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

Справочник по функциям/wp enqueue script

Описание

Безопасный путь добавления JavaScript в страницу, сгенерированную WordPress.

Использование

<?php wp_enqueue_script$handle$src$deps$ver ); ?> Эта функция должна вызываться в привязке к действию wp_enqueue_scripts (для внешней части сайта), admin_enqueue_scripts (для панели управления) или login_enqueue_scripts (для страницы входа).

Параметры

$handle
(string) (required) Название скрипта (рабочее название). Строка в нижнем регистре.
Default: None
$src
(string) (optional) Путь до скрипта от корневой директории WordPress. Например: "/wp-includes/js/scriptaculous/scriptaculous.js". Этот параметр необходим только в случае, если WordPress еще не знает об этом скрипте.
Default: None
$deps
(array) (optional) Массив названий скриптов от которых зависит этот скрипт; скрипты которые должни быть загружены перед этим скриптом. false в случае если нет зависимостей. Этот параметр необходим только в случае, если WordPress еще не знает об этом скрипте.
Default: None
$ver
(string) (optional) Строка указывающая версию скрипта, если она у него есть. По умолчанию false. Этот параметр используется для того чтобы удостовериться, что клиент получил верную версию скрипта, а не из кеша.
Default: None

Примеры

Примечание: Это функция не будет работать, если она вызвана из действия wp_head или wp_print_scripts, поскольку на момент выполнения этих действий скрипты уже должны быть добавлены в очередь. Корректные действия описаны в секции «Использование».

Загружаем штатный скрипт WordPress с нестандартного адреса

Замечание: В темах оформления не рекомендуется использовать сторонние JavaScript- или CSS-файлы по умолчанию, поскольку это ставит пользователей в зависимость от внешнего сервера, к которому у них нет доступа. Гораздо лучше использовать или рекомендовать плагин наподобие Use Google Libraries, который автоматически подключает с серверов Google CDN библиотеку jQuery той же версии, что используется в самом WordPress. Это снижает риск нарушения работы сайта плагинами и темами, в которых жёстко прописаны их собственные копии файла.

Допустим, вы хотите вместо библиотеки jQuery из состава WordPress подключить её CDN-копию. Добавьте этот код в файл functions.php активной темы:

<?php
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

<?php
function my_scripts_method() {
    wp_enqueue_script( 'scriptaculous' );            
}    
 
add_action( 'wp_enqueue_scripts', 'my_scripts_method' ); // На внешней части сайта (т.е. в теме оформления)
?>

Загружаем скрипт, зависящий от scriptaculous

Добавим и загрузим новый скрипт, который зависит от scriptaculous (это также вызывет загрузку scriptaculous на странице):

<?php
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.js была загружена библиотека jQuery:

<?php
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');
?>

Загружаем скрипты плагина только на его страницах

<?php
    add_action( 'admin_init', 'my_plugin_admin_init' );
    add_action( 'admin_menu', 'my_plugin_admin_menu' );
    
    function my_plugin_admin_init() {
        /* Регистрируем наш скрипт. */
        wp_register_script( 'my-plugin-script', plugins_url('/script.js', __FILE__) );
    }
    
    function my_plugin_admin_menu() {
        /* Регистрируем страницу нашего плагина */
        $page = add_submenu_page( 'edit.php', // Родительская страница меню
                                  __( 'Мой плагин', 'myPlugin' ), // Название пункта меню
                                  __( 'Мой плагин', 'myPlugin' ), // Заголовок страницы
                                  'manage_options', // Возможность, определяющая уровень доступа к пункту
                                  'my_plugin-options', // Ярлык (часть адреса) страницы плагина
                                  'my_plugin_manage_menu' // Функция, которая выводит страницу
                               );
   
        /* Используем зарегистрированную страницу для загрузки скрипта */
        add_action( 'admin_print_scripts-' . $page, 'my_plugin_admin_scripts' );
    }
    
    function my_plugin_admin_scripts() {
        /*
         * Эта функция будет вызвана только на странице плагина, подключаем наш скрипт
         */
        wp_enqueue_script( 'my-plugin-script' );
    }
    
    function my_plugin_manage_menu() {
        /* Выводим страницу плагина */
    }
?>

jQuery в режиме noConflict

Примечание: Библиотека jQuery, включенная в WordPress, загружается в режиме «no conflict». Это сделано, чтобы предотвратить проблемы совместимости с другими библиотеками, которые могут загружаться в WordPress.

В режиме «no-confict» ярлык $ недоступен, вместо него используется слово jQuery. Например:

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

нужно переделать так:

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

Чтобы использовать функцию $ как обычно, можно обернуть ваш код в такой фрагмент:

jQuery(document).ready(function($) {
    // Внутри этой функции $() будет работать как синоним jQuery()

});

В этом фрагменте ваш код будет выполнен, когда страница полностью загрузится. Если по какой-то причине вы хотите, чтобы код был выполнен сразу (без ожидания события «ready» в DOM), можно использовать такой фрагмент:

(function($) {
    // Внутри этой функции $() будет работать как синоним jQuery()
})(jQuery);


Штатные скрипты WordPress

Название скрипта Рабочее название Зависимость *
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 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 (Att.: This is not the whole core incl. all core plugins. 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 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
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

* Список зависимостей приведён не полностью.

Ресурсы

This article is marked as in need of editing. You can help Codex by editing it.