В WordPress подключение JavaScript файлов осуществляется с помощью функции wp_enqueue_script(). Эта функция предоставляет удобный и безопасный способ добавить скрипты на страницы вашего сайта. В данной статье мы подробно рассмотрим, как правильно использовать эту функцию, ее параметры и приведем практические примеры.
Зачем использовать wp_enqueue_script?
Использование функции wp_enqueue_script() имеет несколько преимуществ:
- Избежание конфликтов: При правильном подключении скриптов можно избежать конфликтов, связанных с зависимостями. Например, если скрипт зависит от библиотеки jQuery,
wp_enqueue_script()гарантирует, что jQuery будет загружен перед вашим скриптом. - Оптимизация загрузки: Функция позволяет объединять и оптимизировать скрипты для улучшения производительности.
- Контроль версии: Вы можете управлять версиями подключаемых файлов, что поможет избежать проблем с кешированием в браузерах.
- Управление зависимостями: Скрипты будут загружаться в правильном порядке, что исключает ошибки из-за несоответствующих версий.
Основные параметры функции
Функция wp_enqueue_script() принимает несколько параметров:
wp_enqueue_script(
$handle, // Название скрипта
$src, // URL файла скрипта
$deps, // Массив зависимостей
$ver, // Версия скрипта
$in_footer // Загружать в подвале
);- $handle (обязательный) — строка, которая служит уникальным идентификатором для вашего скрипта. Название должно быть в нижнем регистре.
- $src — URL-адрес файла скрипта. Если файл не зарегистрирован, необходимо указать этот параметр.
- $deps — массив идентификаторов скриптов, от которых зависит ваш скрипт.
- $ver — версия скрипта. Если параметр не указан, будет использована версия WordPress.
- $in_footer — логическое значение, указывающее, следует ли загружать скрипт перед закрывающим тегом
</body>(true) или в<head>(false). По умолчанию — false.
Шаблон использования
Чтобы подключить JavaScript файл, необходимо добавить следующий код в файл functions.php вашей темы:
add_action('wp_enqueue_scripts', 'my_scripts_method');
function my_scripts_method() {
wp_enqueue_script('newscript', get_template_directory_uri() . '/js/custom_script.js');
}
В этом примере мы добавляем скрипт custom_script.js, который находится в папке js вашей темы.
Примеры использования
1. Подключение jQuery
WordPress по умолчанию включает библиотеку jQuery, поэтому для её подключения достаточно использовать:
wp_enqueue_script('jquery');2. Подключение собственного скрипта с зависимостью от jQuery
Если ваш скрипт зависит от 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'));
}
3. Динамическое определение версии файла
Чтобы при изменении файла его версия обновлялась, можно использовать filemtime():
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')));
}
Чтобы избежать проблем с кэшированием, можно использовать дату последнего изменения файла как версию. Это гарантирует, что пользователи всегда будут получать последнюю версию скрипта:
/**
* Never worry about cache again!
*/
function my_load_scripts() {
$my_js_ver = date("ymd-Gis", filemtime( plugin_dir_path( __FILE__ ) . 'js/custom.js' ));
$my_css_ver = date("ymd-Gis", filemtime( plugin_dir_path( __FILE__ ) . 'style.css' ));
wp_enqueue_script( 'custom_js', plugins_url( 'js/custom.js', __FILE__ ), array(), $my_js_ver, true );
wp_register_style( 'my_css', plugins_url( 'style.css', __FILE__ ), false, $my_css_ver );
wp_enqueue_style( 'my_css' );
}
add_action( 'wp_enqueue_scripts', 'my_load_scripts' );
4. Подключение скрипта только на определённых страницах
Если нужно подключать скрипты только на определённых страницах, используйте условные теги:
add_action('wp', 'add_my_script_where_it_needed');
function add_my_script_where_it_needed() {
if (is_single()) {
add_action('wp_enqueue_scripts', 'my_scripts_method');
}
}
function my_scripts_method() {
wp_enqueue_script('newscript', get_template_directory_uri() . '/js/newscript.js', array('jquery'));
}
5. Удаление версии из URL скриптов
Если вам нужно удалить версию из URL, используйте следующий код:
add_filter('script_loader_src', 'remove_script_version');
function remove_script_version($src) {
$parts = explode('?', $src);
return $parts[0];
}
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('load-' . $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. Подключение скрипта с условиями
Вы также можете подключать скрипты с условиями, проверяя тип страницы или другие условия:
add_action('wp', 'conditional_script_enqueue');
function conditional_script_enqueue() {
if (is_page('contact')) {
wp_enqueue_script('contact-script', get_template_directory_uri() . '/js/contact.js');
}
}
Скрипты в коробке WordPress
| Название | ИД | Зависимость * | Версия | Лицензия |
|---|---|---|---|---|
| Image Cropper | Image cropper (not used in core, see jcrop) | |||
| Jcrop | jcrop | 0.9.12 | MIT | |
| SWFObject | swfobject | 2.2-20120417 | MIT | |
| SWFUpload | swfupload | 2201-20110113 | MIT | |
| SWFUpload Degrade | swfupload-degrade | 2201 | MIT | |
| SWFUpload Queue | swfupload-queue | 2201 | MIT | |
| SWFUpload Handlers | swfupload-handlers | 2201-20110524 | MIT | |
| jQuery | jquery | json2 (for AJAX calls) | 3.6.0 | MIT + (MIT OR BSD) |
| jQuery Form | jquery-form | jquery | 4.3.0 | MIT OR LGPLv3 |
| jQuery Color | jquery-color | jquery | 2.2.0 | MIT+CC0 + (MIT OR GPLv2) |
| jQuery Masonry | jquery-masonry | jquery | 3.1.2b | MIT |
| Masonry (native Javascript) | masonry | imagesloaded | 4.2.2 | MIT |
| jQuery UI Core | jquery-ui-core | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Widget | Now part of `jquery-ui-core` | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Accordion | jquery-ui-accordion | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Autocomplete | jquery-ui-autocomplete | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Button | jquery-ui-button | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Datepicker | jquery-ui-datepicker | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Dialog | jquery-ui-dialog | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Draggable | jquery-ui-draggable | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Droppable | jquery-ui-droppable | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Menu | jquery-ui-menu | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Mouse | jquery-ui-mouse | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Position | Now part of `jquery-ui-core` | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Progressbar | jquery-ui-progressbar | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Selectable | jquery-ui-selectable | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Resizable | jquery-ui-resizable | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Selectmenu | jquery-ui-selectmenu | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Sortable | jquery-ui-sortable | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Slider | jquery-ui-slider | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Spinner | jquery-ui-spinner | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Tooltips | jquery-ui-tooltip | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Tabs | jquery-ui-tabs | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects | jquery-effects-core | jquery | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Blind | jquery-effects-blind | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Bounce | jquery-effects-bounce | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Clip | jquery-effects-clip | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Drop | jquery-effects-drop | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Explode | jquery-effects-explode | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Fade | jquery-effects-fade | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Fold | jquery-effects-fold | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Highlight | jquery-effects-highlight | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Pulsate | jquery-effects-pulsate | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Scale | jquery-effects-scale | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Shake | jquery-effects-shake | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Slide | jquery-effects-slide | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| jQuery UI Effects – Transfer | jquery-effects-transfer | jquery-effects-core | 1.13.1 | MIT + CC0 + (MIT OR GPLv2) |
| MediaElement.js (WP 3.6+) | wp-mediaelement | jquery | 4.2.16 | MIT |
| jQuery Schedule | schedule | jquery | 20m/1.0.1 | MIT |
| jQuery Suggest | suggest | jquery | 1.1-20110113 | Public domain |
| ThickBox | thickbox | 3.1-20121105 | MIT OR GPLv3 | |
| jQuery HoverIntent | hoverIntent | jquery | 1.10.1 | MIT |
| jQuery Hotkeys | jquery-hotkeys | jquery | 0.2.0 | MIT OR GPLv2 |
| Simple AJAX Code-Kit | sack | 1.6.1 | X11 License | |
| QuickTags | quicktags | 1.3 | LGPL2.1 | |
| Iris (Colour picker) | iris | jquery | 1.1.1 | GPLv2 |
| Farbtastic (deprecated) | farbtastic | jquery | 1.2 | GPLv3 |
| ColorPicker (deprecated) | colorpicker | jquery | v2 | Author’s own copyright |
| Tiny MCE | wp-tinymce | 4.9.4 | LGPL2.1 | |
| 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 | 2015-05-03 | Public domain | |
| Plupload Core | plupload | 2.1.9 | GPLv2 | |
| Plupload All Runtimes | plupload-all | 2.1.1 | GPLv2 | |
| Plupload HTML4 | plupload-html4 | 2.1.1 | GPLv2 | |
| Plupload HTML5 | plupload-html5 | 2.1.1 | GPLv2 | |
| Plupload Flash | plupload-flash | 2.1.1 | GPLv2 | |
| Plupload Silverlight | plupload-silverlight | 2.1.1 | GPLv2 | |
| Underscore js | underscore | 1.13.1 | MIT | |
| Backbone js | backbone | jquery, underscore | 1.4.0 | MIT |
| imagesLoaded | imagesloaded | 4.1.4 | MIT | |
| CodeMirror | wp-codemirror | 5.29.1-alpha-ee20357 | MIT | |
| imgAreaSelect | imgareaselect | jquery | 0.9.8 | MIT AND GPL |
| Удалены | |||
|---|---|---|---|
| Имя | ИД | Удалено с версии | Заменено на |
| Scriptaculous Root | scriptaculous-root | WP 3.5 | Google Version |
| Scriptaculous Builder | scriptaculous-builder | WP 3.5 | Google Version |
| Scriptaculous Drag & Drop | scriptaculous-dragdrop | WP 3.5 | Google Version |
| Scriptaculous Effects | scriptaculous-effects | WP 3.5 | Google Version |
| Scriptaculous Slider | scriptaculous-slider | WP 3.5 | Google Version |
| Scriptaculous Sound | scriptaculous-sound | WP 3.5 | Google Version |
| Scriptaculous Controls | scriptaculous-controls | WP 3.5 | Google Version |
| Scriptaculous | scriptaculous | WP 3.5 | Google Version |
| Prototype Framework | prototype | WP 3.5 | Google Version |
Заключение
Функция wp_enqueue_script() — мощный инструмент для управления загрузкой JavaScript файлов в WordPress. Правильное использование этой функции помогает избежать конфликтов, оптимизирует производительность и обеспечивает гибкость при работе с зависимостями. С помощью примеров, приведенных выше, вы можете эффективно подключать скрипты к вашей теме или плагину, учитывая все необходимые детали.