Как правильно добавлять пользовательские JavaScript файлы на сайт?

В дополнение к прекрасной иллюстрации Майка о использовании enqueue, хочу отметить, что скрипты, включенные как зависимости, не нужно регистрировать отдельно...

Я воспользуюсь примером под заголовком Scripts in a Plugin в ответе Майка.

define('MY_PLUGIN_VERSION','2.0.1');

add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue_scripts' );
function my_plugin_enqueue_scripts() {
    wp_enqueue_script('jquery');
    wp_enqueue_script('jquery-ui-sortable');
    wp_enqueue_script('my-script',plugins_url('/js/my-script.js',__FILE__),array('jquery','jquery-ui-sortable'),MY_PLUGIN_VERSION);
}

Это можно сократить до следующего вида:

define('MY_PLUGIN_VERSION','2.0.1');

add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue_scripts' );
function my_plugin_enqueue_scripts() {
    wp_enqueue_script('my-script', plugins_url( '/js/my-script.js', __FILE__ ), array('jquery','jquery-ui-sortable'), MY_PLUGIN_VERSION);
}

Когда вы указываете зависимости, WordPress автоматически найдет и зарегистрирует их для вашего скрипта, поэтому вам не нужно делать отдельные вызовы для этих скриптов.

Кроме того, некоторые из вас могут задаться вопросом: может ли указание нескольких зависимостей привести к неправильному порядку загрузки скриптов? Приведу пример:

wp_enqueue_script( 'first-script', 'example/path/example_script_1.js', array('second-script','third-script') );

Если второй скрипт зависит от третьего (т.е. третий скрипт должен загружаться первым), это не имеет значения. WordPress определит приоритеты регистрации для этих скриптов и выведет их в правильном порядке. Короче говоря, WordPress автоматически разберется за вас.

Для небольших фрагментов скриптов, которые вы, возможно, не хотите включать в отдельный файл (например, потому что они генерируются динамически), WordPress 4.5 и выше предлагает функцию wp_add_inline_script. Эта функция, по сути, прикрепляет скрипт к другому скрипту.

Допустим, например, что вы разрабатываете тему и хотите, чтобы ваш клиент мог вставлять свои собственные скрипты (например, Google Analytics или AddThis) через страницу настроек. В этом случае вы можете использовать wp_add_inline_script, чтобы прикрепить этот скрипт к вашему основному JS-файлу (например, mainjs) следующим образом:

$custom_script = get_option('my-script')
if (!empty($custom_script)) wp_add_inline_script ('mainjs', $custom_script);

Мой предпочтительный способ достижения хорошей производительности — вместо использования wp_enqueue_script я применяю HEREDOC с Fetch API для асинхронной параллельной загрузки всего:

$jquery_script_path = '/wp-includes/js/jquery/jquery.js?ver=1.12.4';
$jquery_dependent_script_paths = [
  get_theme_file_uri( '/assets/js/global.js' ),
  get_theme_file_uri( '/assets/js/jquery.scrollTo.js' ),
  get_theme_file_uri( '/assets/js/skip-link-focus-fix.js' ),
  get_theme_file_uri( '/assets/js/navigation.js' )
];
$jquery_dependent_script_paths_json = json_encode($jquery_dependent_script_paths);
$inline_scripts = <<<EOD
<script>
(function () {
  'use strict';
  if (!window.fetch) return;
  /**
   * Fetch Inject v1.6.8
   * Copyright (c) 2017 Josh Habdas
   * @licence ISC
   */
  var fetchInject=function(){"use strict";const e=function(e,t,n,r,o,i,c){i=t.createElement(n),c=t.getElementsByTagName(n)[0],i.type=r.blob.type,i.appendChild(t.createTextNode(r.text)),i.onload=o(r),c?c.parentNode.insertBefore(i,c):t.head.appendChild(i)},t=function(t,n){if(!t||!Array.isArray(t))return Promise.reject(new Error("`inputs` must be an array"));if(n&&!(n instanceof Promise))return Promise.reject(new Error("`promise` must be a promise"));const r=[],o=n?[].concat(n):[],i=[];return t.forEach(e=>o.push(window.fetch(e).then(e=>{return[e.clone().text(),e.blob()]}).then(e=>{return Promise.all(e).then(e=>{r.push({text:e[0],blob:e[1]})})}))),Promise.all(o).then(()=>{return r.forEach(t=>{i.push({then:n=>{"text/css"===t.blob.type?e(window,document,"style",t,n):e(window,document,"script",t,n)}})}),Promise.all(i)})};return t}();
  fetchInject(
    $jquery_dependent_script_paths_json
  , fetchInject([
    "{$jquery_script_path}"
  ]));
})();
</script>
EOD;

Затем я вставляю их в head, иногда вместе со стилями, вот так:

function wc_inline_head() {
  global $inline_scripts;
  echo "{$inline_scripts}";
  global $inline_styles;
  echo "{$inline_styles}";
}

В результате получается водопадная загрузка, которая выглядит так — всё загружается одновременно, но порядок выполнения контролируется:

Примечание: Для этого требуется использование Fetch API, который поддерживается не во всех браузерах.