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()