WordPress 加載 JS 函數:wp_enqueue_script()

函數説明

使用 wp_enqueue_script() 函數安全的將 JavaScript 腳本添加到 WordPress 生成的頁面。 wp_enqueue_script() 函數會加載未被加載的腳本，並安全的處理依賴關係。

函數用法

<?php wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ); ?>

使用 wp_enqueue_scripts 動作調用 wp_enqueue_script() 函數，或者使用 admin_enqueue_scripts 動作在管理頁面調用 wp_enqueue_script() 函數，或者使 login_enqueue_scripts 動作在登錄頁面調用 wp_enqueue_script() 函數。

參數説明

$handle
(string) (required) 腳本名稱，使用小寫字母。
Default: None

$src
(string) (optional) 腳本的鏈接。例如：」http://example.com/wp-includes/js/scriptaculous/scriptaculous.js」。 $src 參數僅在 WordPress 沒有內置當前時是必填項，$src 參數是必填項。你不需要寫死腳本鏈接，針對插件使用 plugins_url() 函數，針對主題使用 get_template_directory_uri() 函數獲取正確的鏈接。
Default: false

$deps
(array) (optional) 當前腳本依賴的腳本數組（必須在當前腳本之前加載）。如果沒有依賴關係則 $deps 參數失效。 $deps 參數僅在 WordPress 沒有內置當前腳本時是必填項。
Default: array()

$ver
(string) (optional) 指定腳本版本號的字符串，如果設置 $ver 參數，WordPress 會自動把 $ver 參數作為查詢字符串連接到路徑末尾。默認為 false 。如果 $ver 參數沒有設置或者設置為 false，WordPress 會自動把當前 WordPress 的版本號連接到路徑末尾。如果 $ver 參數設置為 null 則不添加版本信息。 $ver 參數用於確保傳遞給客户端的正確版本不受緩存影響，因此讓腳本附加版本號是有道理的。

$in_footer
(boolean) (optional) 通常腳本位於

區域。如果 $in_footer 參數設置為 true，腳本會位於底部。 $in_footer 參數需要主題在適當的位置有 wp_footer() 鈎子。請注意，您必須在 wp_head 運行之前加載當前腳本，即使腳本放置在頁腳。
Default: false

返回值

(void) wp_enqueue_script() 函數無返回值。

實例

請注意：如果使用 wp_head 或 wp_print_scripts 動作鈎子調用 wp_enqueue_script() 函數，則 wp_enqueue_script() 函數不會運行，js 腳本需要在這些動作鈎子運行前載入。參考上面的用法章節正確使用鈎子。

從一個非 WordPress 默認位置加載默認 WordPress 腳本
請注意：不推薦主題強制默認使用第三方提供服務的 JavaScript 或 CSS 文件，這麼做會讓用户依賴於一個不受用户控制的外部主機。一個更好的選擇是使用/推薦一個插件，例如：Use Google Libraries 插件，此插件自動使用 Google-CDN 提供的和 WordPress 同一版本的 jQuery，最終降低又主題或插件中寫死文件造成的破壞風險。

警告：在插件中使用卸載 WordPress 內置的腳本的方法將被拒絕執行。

假設你要使用 CDN 的 jQuery 版本替換 WordPress 內置版本，將如下代碼添加到 functions.php 文件。

function my_scripts_method() {
	wp_deregister_script( 'jquery' );
	wp_register_script( 'jquery', 'http://googleajax.admincdn.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 腳本

function my_scripts_method() {
        wp_enqueue_script('scriptaculous');
}

add_action('wp_enqueue_scripts', 'my_scripts_method');

上述代碼只在前端頁面加載 Scriptaculous 腳本庫，如果你需要在管理頁面加載，可以使用 admin_enqueue_scripts 動作鈎子調用，但是腳本會在所有管理頁面載入，這樣往往會導致插件/核心衝突，最終破壞 WordPress 的管理體驗。相反，你應該只在你需要的單獨頁面加載腳本，參考只在插件的頁面部分加載腳本的例子。

加載依賴於 Scriptaculous 的腳本
加載一個依賴於 Scriptaculous 的新腳本。這將導致 WordPress 在加載當前腳本前先將 Scriptaculous 腳本加載到頁面。

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 JavaScript 腳本需要先加載 jQuery 腳本：

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

僅在插件頁面加載腳本

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_scripts-' . $page, 'my_plugin_admin_scripts');
}

function my_plugin_admin_scripts() {
	/*
	* 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 */
}

jQuery 無衝突模式封裝
請注意：WordPress 內置 jQuery 腳本庫加載使用無衝突模式，這是為了防止與其他 WordPress 可以加載的 JavaScript 庫的兼容性問題。

無衝突模式下，$() 函數無效，使用 jQuery() 函數。例如：

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

變成:

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

為了使用 jQuery 默認的 shortcut $，你可以使用如下封裝代碼：

jQuery(document).ready(function($) {
	// $() will work as an alias for jQuery() inside of this function
});

上述封裝將導致你的代碼在頁面加載完成後執行。 $會調用 jQuery 。如果你想讓代碼立即執行，你可以使用下面的封裝方法：

(function($) {
	// $() will work as an alias for jQuery() inside of this function
})(jQuery);

源文件

wp_enqueue_script() 位於 wp-includes/functions.wp-scripts.php

WordPress 加載 JS 函數:wp_enqueue_script()