WordPress как на ладони
wordpress jino

wp_enqueue_script() WP 2.1

Правильно подключает скрипт (JavaScript файл) на страницу.

Использовать эту функцию для подключения js файлов важно, потому что так вы в дальнейшем сможете без лишних проблем объединять JS файлы в один. Также в некоторых случаях избавитесь от конфликтов скриптов, когда зависимый скрипт подключается после того от которого он зависит.

wp_enqueue_script() добавляет скрипт, только если он еще не был добавлен и другие скрипты от которых он зависит зарегистрированы. Зависимые скрипты добавляются автоматически.

Если скрипт уже зарегистрирован с помощью wp_register_script(), то для его подключения в wp_enqueue_script() нужно указать только ярлык скрипта (в первом параметре).

// jquery регистрируется в WP по умолчанию.
// Поэтому для его подключения достаточно одной строки:
wp_enqueue_script('jquery');

Если скрипт не зарегистрирован, то его можно зарегистрировать и подключить одной функцией - wp_enqueue_script():

 wp_enqueue_script('newscript', get_template_directory_uri() . '/js/custom_script.js');

С версии 3.3. wp_enqueue_script() можно вызывать во время генерации страницы. В этом случае вызываемый скрипт будет подключен в подвале, в момент срабатывания события wp_footer.

Функция обычно вызываться во время следующих событий (вешаться на хуки):

  • wp_enqueue_scripts - для внешней части сайта;
  • admin_enqueue_scripts - для админ-панели;
  • login_enqueue_scripts  - для страницы входа.

Когда нужно подключить скрипт с условием, например, <!--[if lt IE 9]>...<![endif]--> используйте в дополнении к этой функцию wp_script_add_data()

Оглавление:
Используется в: the_custom_header_markup().

Хуков нет.

Возвращает

Ничего не возвращает.

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

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

Шаблон использования

//add_action( 'admin_enqueue_scripts', 'my_scripts_method' );
//add_action( 'login_enqueue_scripts', 'my_scripts_method' );
add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
function my_scripts_method(){
	wp_enqueue_script( 'newscript', get_template_directory_uri() . '/js/custom_script.js');
}

Параметры

$handle(строка) (обязательный)

Название скрипта (рабочее название). Строка в нижнем регистре.

Если строка содержит знак вопроса (?): scriptaculous&v=1.2, то предшествующая часть будет названием скрипта, а все что после будет добавлено в УРЛ как параметры запроса. Так можно указывать версию подключаемого скрипта.

$src(строка)

УРЛ файла скрипта. Например: http://example.com/wp-content/themes/my-theme/my-theme-script.js.

Этот параметр необходим только, когда скрипт не зарегистрирован и WordPress еще не знает об этом скрипте, смотрите функцию wp_register_script().

Не нужно писать УРЛ жестко, он должен определяться динамически. Для этого используйте функции получения URL:

Ссылки на внешние скрипты можно указывать без указания протокола: //otherdomain.com/js/their-script.js.

Уже зарегистрированные в WP скрипты смотрите ниже в этой статье.

По умолчанию: false

$deps(массив)
Массив названий скриптов от которых зависит этот скрипт; скрипты которые должны быть загружены перед этим скриптом. Этот параметр необходим только в случае, если WordPress еще не знает об этом скрипте.
По умолчанию: array()
$ver(строка)

Строка указывающая версию скрипта, если она у него есть. Этот параметр используется для того чтобы удостовериться, что клиент получил верную версию скрипта, а не из кеша.

Если параметр не указан, то в качестве версии скрипта будет использована версия WordPress.

Если указать null, то никакая версия не будет добавлена.

По умолчанию: false

$in_footer(логический)

Подключить скрипт в подвал?

Обычно скрипт подключается в <head> документа, если указать true, то скрипт будет подключен перед тегом </body>, точнее там где вызывается тег шаблона wp_footer().

Если из-за зависимости от других скриптов нет возможности подключить текущий скрипт в подвале, то значение этой переменой будет проигнарировано.

Для понятного чтения кода, вместо true можно указать любую строку, например 'in_footer'.

По умолчанию: false

Примеры

#1 Загружаем базовый скрипт WordPress с нестандартного адреса.

Допустим, вы хотите вместо библиотеки jQuery из состава WordPress подключить её CDN-копию. Добавьте этот код в файл functions.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', 11 );

Используя фильтр wp_enqueue_scripts (вместо фильтра init, на который ссылаются некоторые статьи на сторонних сайтах), мы избегаем регистрации альтернативной версии jQuery на страницах панели управления, что (среди прочего) снижает риск нарушения работы редактора записей при обновлении.

#2 Загружаем штатный скрипт scriptaculous.

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

#3 Регистрируем и подключаем свой скрипт, зависящий от jQuery

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

add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
function my_scripts_method() {
	$script_url = plugins_url( '/js/newscript.js', __FILE__ );
	wp_enqueue_script('custom-script', $script_url, array('jquery') );
}

#4 Подгружаем скрипт только для нужных типов страниц

Допустим нам нужно использовать условные теги, чтобы подгрузить свой скрипт scriptaculous. Тогда мы может подключиться на хук wp, в момент его срабатывания мы уже можем использовать условные теги, поэтому через него мы можем определить для каких типов страниц подключить скрипт, а для каких нет:

add_action('wp', 'add_my_script_where_it_necessery');
function add_my_script_where_it_necessery(){
	if( is_single() )
		add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
}
function my_scripts_method() {
	$script_url = plugins_url( '/js/newscript.js', __FILE__ );
	wp_enqueue_script('newscript', $script_url, array('scriptaculous') );
}

#5 Загружаем в теме оформления скрипт, зависящий от скрипта в WordPress

Часто требуется, чтобы перед JavaScript-файлами, поставляемыми с темой оформления, был загружен другой JavaScript-файл. WordPress предоставляет API, позволяющий при регистрации скрипта указать его зависимости. Например, тема с приведённым ниже кодом требует, чтобы перед скриптом custom_script.js была загружена библиотека jQuery:

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

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

add_action( 'admin_menu', 'my_plugin_admin_menu' );
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', plugins_url('/script.js', __FILE__) );
}

function my_plugin_manage_menu() {
	// Выводим страницу плагина
}

#7 Как подключить jquery из Google

Читайте в отдельной статье.

#8 Динамическое определение версии файла

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

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

Производительность filemtime( get_theme_file_path('js/custom_script.js') ) очень высока - на SSD диске 0,5 сек на 50к итераций - это очень быстро!

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

Название скрипта ID Зависимость
Image Cropper Image cropper (not used in core, see jcrop)
Jcrop jcrop
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 Masonry jquery-masonry jquery
Masonry (native Javascript) masonry
jQuery UI Core jquery-ui-core jquery
jQuery UI Widget jquery-ui-widget jquery
jQuery UI Accordion jquery-ui-accordion jquery
jQuery UI Autocomplete jquery-ui-autocomplete jquery
jQuery UI Button jquery-ui-button jquery
jQuery UI Datepicker jquery-ui-datepicker jquery
jQuery UI Dialog jquery-ui-dialog jquery
jQuery UI Draggable jquery-ui-draggable jquery
jQuery UI Droppable jquery-ui-droppable jquery
jQuery UI Menu jquery-ui-menu jquery
jQuery UI Mouse jquery-ui-mouse jquery
jQuery UI Position jquery-ui-position jquery
jQuery UI Progressbar jquery-ui-progressbar jquery
jQuery UI Selectable jquery-ui-selectable jquery
jQuery UI Resizable jquery-ui-resizable jquery
jQuery UI Selectmenu jquery-ui-selectmenu jquery
jQuery UI Sortable jquery-ui-sortable jquery
jQuery UI Slider jquery-ui-slider jquery
jQuery UI Spinner jquery-ui-spinner jquery
jQuery UI Tooltips jquery-ui-tooltip jquery
jQuery UI Tabs jquery-ui-tabs jquery
jQuery UI Effects jquery-effects-core jquery
jQuery UI Effects - Blind jquery-effects-blind jquery-effects-core
jQuery UI Effects - Bounce jquery-effects-bounce jquery-effects-core
jQuery UI Effects - Clip jquery-effects-clip jquery-effects-core
jQuery UI Effects - Drop jquery-effects-drop jquery-effects-core
jQuery UI Effects - Explode jquery-effects-explode jquery-effects-core
jQuery UI Effects - Fade jquery-effects-fade jquery-effects-core
jQuery UI Effects - Fold jquery-effects-fold jquery-effects-core
jQuery UI Effects - Highlight jquery-effects-highlight jquery-effects-core
jQuery UI Effects - Pulsate jquery-effects-pulsate jquery-effects-core
jQuery UI Effects - Scale jquery-effects-scale jquery-effects-core
jQuery UI Effects - Shake jquery-effects-shake jquery-effects-core
jQuery UI Effects - Slide jquery-effects-slide jquery-effects-core
jQuery UI Effects - Transfer jquery-effects-transfer jquery-effects-core
MediaElement.js (WP 3.6+) wp-mediaelement jquery
jQuery Schedule schedule jquery
jQuery Suggest suggest jquery
     
ThickBox thickbox
jQuery HoverIntent hoverIntent jquery
jQuery Hotkeys jquery-hotkeys jquery
Simple AJAX Code-Kit sack
QuickTags quicktags
Iris (Colour picker) iris jquery
Farbtastic (deprecated) farbtastic jquery
ColorPicker (deprecated) colorpicker jquery
Tiny MCE tiny_mce
Heartbeat heartbeat jquery
Autosave autosave
WordPress AJAX Response wp-ajax-response
List Manipulation wp-lists
WP Common common
WP Editor editorremov
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-reply
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 Core plupload
Plupload All Runtimes plupload-all
Plupload HTML4 plupload-html4
Plupload HTML5 plupload-html5
Plupload Flash plupload-flash
Plupload Silverlight plupload-silverlight
Underscore js underscore
Backbone js backbone

Это не полный список. Для получения полного списка изучите глобальную переменную $GLOBALS['wp_scripts'], находясь в админ-панели. Зарегистрированные скрипты могут меняться в зависимости от страницы панели на которой вы находитесь.

Актуальный список можно посмотреть в коде функции wp_default_scripts()

Заметки

В версии 3.5 WordPress изменил положение о минимизации скриптов и CSS стилей. До этого минимизированные файлы имели расширения: .js и .css соответственно, а не минимизированные .dev.js и .dev.css. Теперь, минимизированные файлы имеют расширение: .min.js и .min.css, а обычные .js и .css.

Код wp enqueue script: wp-includes/functions.wp-scripts.php WP 4.8.2

<?php
function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $in_footer = false ) {
	$wp_scripts = wp_scripts();

	_wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );


	if ( $src || $in_footer ) {
		$_handle = explode( '?', $handle );

		if ( $src ) {
			$wp_scripts->add( $_handle[0], $src, $deps, $ver );
		}

		if ( $in_footer ) {
			$wp_scripts->add_data( $_handle[0], 'group', 1 );
		}
	}

	$wp_scripts->enqueue( $handle );
}

Cвязанные функции

Из метки: script

Еще из раздела: Регистрация script и style

wp_enqueue_script 60 комментариев
Полезные 5 Вопросы 3 Все
  • Denfr86-1 cайт: denfrolov.ru

    Всем привет
    wp_enqueue_script( 'basic-scripts', get_template_directory_uri() . '/js/functions.js', array( 'jquery' ), true, true );

    Разбираю тему - basic, может кто в курсе? Первый тру говорит о том что скрипт загружается в футере, а второй зачем?

    -1
  • Дмитрий

    Здравствуйте. Что то не пойму, а этот есть в наличии вордпресса https://code.jquery.com/ui/1.10.4/jquery-ui.js

    • campusboy1848 cайт: wp-plus.ru

      Привет. Смотри таблицу, там же усё написано. В WP jquery-ui.js разбит на модули, чтобы не тянуть всю связку, если, к примеру, надо всего лишь 1 компонент.

      1
      • Дмитрий

        Спасибо. Таблицу то я смотрел, только не знал, что скрипт на модули разбит.

        • campusboy1848 cайт: wp-plus.ru

          Не за что. В общем, подключаете ядро и затем нужный модуль smile Или сразу модуль и указываете ему зависимость от ядра и оно автоматом подключится.

          • Kama4464

            Зависимости указывать не обязательно, можно просто модуль подключать и он сам jQuery подключит, там при реге уже все зависимости указаны... yes

            2
  • Андрей

    Как подключить 2 стандартных скрипта вордпрессовских jquery и jquery-form, а то во всех примерах один стандартный, а второй свой.

    • Kama4464
      add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
      function my_scripts_method(){
      	wp_enqueue_script( 'jquery-form' );
      }

      И все...

      • Андрей

        Странно, так тоже пробовал. Чет упорно не хотят появляться в списке подключенных, что только я не пробовал подключать. В шаблон добавлены и wp_head и wp_footer. В чем может быть причина?

  • campusboy1848 cайт: wp-plus.ru

    Не особо понял, зачем в 6 примере мы использовали:

    add_action( 'admin_init', 'my_plugin_admin_init' );
    
    function my_plugin_admin_init() {
    	/* Регистрируем наш скрипт. */
    	wp_register_script( 'my-plugin-script', plugins_url('/script.js', __FILE__) );
    }

    Как по мне лишнее телодвижение или есть подводные камни?

    1
    Ответить4 месяца назад #
  • Макс cайт: motelamur.ru

    Привет! А почему этот скрипт не переносится в футер?
    Захотел подключить скрипт от яндекс поделиться. Вот так его прописал в functions.php

    add_action( 'wp_enqueue_scripts', 'ya_share' );
    function ya_share(){
    	wp_enqueue_script( 'share', '//yastatic.net/share2/share.js', 1, true);
    }

    а он зараза в head цепляется. Что можно сделать?

    Ответить4 месяца назад #
    • campusboy1848 cайт: wp-plus.ru

      Привет. Потому что неправильно передал параметры. Параметр, отвечающий за показ в футере должен идти пятым:

      add_action( 'wp_enqueue_scripts', 'ya_share' );
      function ya_share(){
      	wp_enqueue_script( 'share', '//yastatic.net/share2/share.js', array(), null, true);
      }
      2
      Ответить4 месяца назад #
  • Андрей

    А как быть если у меня на сайте кроме основной темы, есть ещё личный кабинет. Как сделать так, чтобы у меня подключался другой набор скриптов и стилей для него?

    Ответить22 дня назад #
    • Kama4464

      Условными тегами условия проставь где и что подключать...

      Ответить20 дней назад #
  • Андрей

    Как правильно подключить js скрипты к Дочерней теме?

    Спасибо.

    Ответить2 дня назад #
    • через функцию get_stylesheet_directory_uri()

      Общий вид такой:

      function scripts_single_product(){
      	wp_enqueue_script( 'scriptname', get_stylesheet_directory_uri() . '/woocommerce/single-product/scriptname.js');
      }
      
      add_action( 'wp_enqueue_scripts', 'scripts_single_product' );

      P.s. здесь подробней про эту функцию: get_stylesheet_directory_uri()

      1
      Ответить2 дня назад #

Здравствуйте, !

Ваш комментарий