• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/wp enqueue script

提供: WordPress Codex 日本語版
移動先: 案内検索

このページ「関数リファレンス/wp enqueue script」は一部未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

説明

スクリプトファイルがまだインクルードされていない場合、また、すべての依存するスクリプトが登録済みの場合、依存関係に従った適切なタイミングでファイルを生成されたページにリンクします。スクリプトのリンクは、wp_register_script() 関数ですでに登録済みのハンドル、またはこの関数に必要なパラメータを与えることで行えます。

これは WordPress が生成するページに JavaScript をリンクする際に推奨されている方法です。

使い方

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

この関数を呼び出す際に使うべきアクションフックについての情報はセクションをご覧ください。

パラメータ

$handle
文字列) (必須) スクリプトのハンドルとして使われる名前。特別なケースとして、文字列に '?' という記号が含まれている場合、それより前の部分は登録されたハンドルとして参照され、それより後の部分はクエリストリングとして URL に追加される。このような特別な場合、バージョンを使用する必要がある。
初期値: なし
$src
文字列) (オプション) スクリプトの URL。例: http://example.com/wp-content/themes/my-theme/my-theme-script.js。ローカルスクリプトの URL は絶対に直接書き込むべきではない。代わりに plugins_url (プラグイン向け) と get_template_directory_uri (テーマ向け) を使って適切な URL を取得する。リモートのアセットはプロトコルに影響されない URL で指定できる。例: //otherdomain.com/js/their-script.js。「WordPress に含まれ登録されているデフォルトスクリプト」を参照。
初期値: false
$deps
配列) (オプション) このスクリプトが依存するスクリプトのハンドルの配列、つまり、このスクリプトより前に読み込まれる必要があるスクリプト。このパラメータは、$handle のスクリプトが wp_register_script() を使って登録されていない場合のみに必要。デフォルトのハンドルはすべて小文字。
初期値: array()
$ver
文字列) (オプション) クエリストリングとしてファイルパスの最後に連結される、スクリプトのバージョン番号を指定する文字列 (存在する場合) 。バージョンが指定されていない場合は false に設定され、WordPress は自動的に現在の WordPress のバージョン数と同じバージョン番号を追加する。null に設定した場合はバージョン番号は追加されない。このパラメータはキャッシングに関わらず正しいバージョンがクライアントに送信されるようにするために使う。したがって、バージョン番号があってそれがスクリプトに意味を持つ場合は含めるべきである。
初期値: false
$in_footer
真偽値) (オプション) スクリプトは通常 HTML ドキュメントの <head> に置かれるが、もしこのパラメータが true の場合 </body> 終了タグの前に配置される。テーマ内の適切な位置に wp_footer() テンプレートタグが含まれていることが必須となる。
初期値: false

戻り値

(void) 
この関数には戻り値はありません。

用例

フックを使う

ひとつのアクションフックでスクリプトとスタイルをエンキューする。

/**
 * スクリプトとスタイルを正しくエンキューする方法
 */
function theme_name_scripts() {
	wp_enqueue_style( 'style-name', get_stylesheet_uri() );
	wp_enqueue_script( 'script-name', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );
}

add_action( 'wp_enqueue_scripts', 'theme_name_scripts' );

script.aculo.us ライブラリをリンクする

以下は、 scriptaculous ハンドルで、WordPressによって すでにインクルード、登録されている script.aculo.us ライブラリとをリンクさせる基本的な使い方の例です。

<?php
function my_scripts_method() {
    wp_enqueue_script( 'scriptaculous' );
}

add_action( 'wp_enqueue_scripts', 'my_scripts_method' ); // wp_enqueue_scripts アクションフックはフロントエンドのみでリンク
?>

上記の例は script.aculo.us ライブラリとフロントエンドでのみリンクします。 ライブラリが管理画面 で必要な場合、代わりに admin_enqueue_scripts アクション フック を使用することができます。ですが、この場合、 全て の管理画面でエンキューしてしまい、プラグインやコアとのコンフリクトを生み、究極的にはWordPressの管理画面でのエクスペリエンスを損なう可能性があります。それよりも、必要な各画面でのみリンクするべきです。例に関しては、 プラグイン管理画面のみでスクリプトをリンクする セクションを参照してください。

JQuery に依存するテーマのスクリプトをリンクする

テーマにインクルードされる JavaScript ファイルは、ある関数や変数を使うために、別の JavaScript ファイルが予め読み込まれている必要性を持つことがよくあります。$deps パラメータを利用してwp_enqueue_script()wp_register_script() は新しいスクリプトを登録するときに依存先を指定できます。これにより WordPress は、新しいスクリプトをリンクする前にこれらの依存先を HTML ページへリンクします。もし依存先を表すハンドル登録されていない場合、WordPress は新しいスクリプトをリンクしません。次の例は custom_script.js テーマスクリプトが jQuery ライブラリを必要とする場合です:

<?php
/**
 * Enqueue a script with jQuery as a dependency.
 */
function wpdocs_scripts_method() {
    wp_enqueue_script( 'custom-script', get_stylesheet_directory_uri() . '/js/custom_script.js', array( 'jquery' ) );
}
add_action( 'wp_enqueue_scripts', 'wpdocs_scripts_method' );
?>

script.aculo.us に依存するプラグインのスクリプトをリンクする

次の例はプラグインファイル内での使用を想定したもので、script.aculo.us ライブラリに依存する新しいプラグインスクリプトを登録およびリンクします。依存先については上の例を見てください。

/**
 * Enqueue script with script.aculo.us as a dependency.
 */
function my_scripts_method() {
    wp_enqueue_script( 'newscript', plugins_url( '/js/newscript.js' , __FILE__ ), array( 'scriptaculous' ) );
}
add_action( 'wp_enqueue_scripts', 'my_scripts_method' );

プラグイン管理画面のみでスクリプトをリンクする

次の例はスクリプトを特定の管理画面でのみリンクします。これは最初の例のコードの下で説明したシナリオと対になるものです。

<?php
/**
 * プラグインのスクリプトを登録する。
 */
function wpdocs_plugin_admin_init() {
    // スクリプトを登録。
    wp_register_script( 'my-plugin-script', plugins_url( '/script.js', __FILE__ ) );
}
add_action( 'admin_init', 'wpdocs_plugin_admin_init' );
 
/**
 * プラグインの管理画面を追加する。
 */
function wpdocs_plugin_admin_menu() {
    /* プラグインのサブメニューと管理画面を追加 */
    $page_hook_suffix = add_submenu_page( 'edit.php',   // サブメニューの親ページ。
        __( 'My Plugin', 'my-textdomain' ),             // サブメニューのタイトル。
        __( 'My Plugin', 'my-textdomain' ),             // 画面のタイトル。
        'manage_options',                               // サブメニューのアクセスに必要な権限。
        'my_plugin-options',                            // 画面の URL で使うスラッグ。
        'wpdocs_plugin_manage_menu'                     // 画面を表示するために呼び出す関数。
    );
 
    /*
     * 取得した $page_hook_suffix を使って、スクリプトをリンクする関数をフックする。
     * このフックはプラグインの管理画面でのみ起動される。
     * 参照: https://developer.wordpress.org/reference/hooks/admin_print_scripts-hook_suffix/
     */
    add_action( "admin_print_scripts-{$page_hook_suffix}", 'wpdocs_plugin_admin_scripts');
}
add_action( 'admin_menu', 'wpdocs_plugin_admin_menu' );
 
/**
 * 登録済みスクリプトを管理画面へエンキューする。
 */
function wpdocs_plugin_admin_scripts() {
    // 登録済みスクリプトをページへリンク。
    wp_enqueue_script( 'my-plugin-script' );
}
 
/**
 * プラグインの管理画面を表示するためのコールバック。
 */
function wpdocs_plugin_manage_menu() {
    // プラグインの管理画面を表示。
}

子テーマから依存関係のないスクリプトを読み込む

フッターで、依存関係のない同じコールバック関数にスクリプトを登録してエンキューします。 詳細については、 wp_register_script() を参照してください。 この例では、 google_analytics_object.js は Google アナリティクスのトラッキングコードが書かれたファイルです。

<?php
add_action( 'wp_enqueue_scripts', 'child_add_scripts' );

/**
 * JavaScript ライブラリに依存しないスクリプトを登録してエンキューする。
 */
function child_add_scripts() {
    wp_register_script(
        'google-analytics',
        get_stylesheet_directory_uri() . '/google_analytics_object.js',
        false,
        '1.0',
        true
    );

    wp_enqueue_script( 'google-analytics' );
}

jQuery noConflict ラッパー

WordPress に含まれる jQuery ライブラリは noConflict() モードに設定されます (wp-includes/js/jquery/jquery.js を参照) 。これは WordPress に含まれる他の JavaScript ライブラリとの互換性の問題を防ぐためです。 noConflict モードの場合、以下のような書き方で jQuery を使用できます。

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

しかし、下記のようにコードを書くとエラーが発生するか、他のライブラリの $() が使用されてしまいます。

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

どうしても jQuery() の代わりに $() を使いたければ、以下のようにラッパーで囲むと使うことができます。

jQuery(document).ready(function($) {
    // この関数内では $() を jQuery() のエイリアスとして利用可能です
    // そして、$() を使う他のライブラリはこの関数内では利用できません
});

このラッパーによって、あなたのコードは DOM の構築終了時に実行されます。何らかの理由で DOM ready イベントを待たずにすぐコードを実行したい場合は、代わりに以下のラッパーメソッドを使用できます。

(function($) {
    // この関数内では $() を jQuery() のエイリアスとして利用可能です
    // そして、$() を使う他のライブラリはこの関数内では利用できません
})(jQuery);

あるいは、以下のように定義すれば jQuery() のように書く代わりに $j() というショートカットを使えます。このとき $() は他のライブラリのものとして使えます。

var $j = jQuery;

WordPress に含まれ登録されているデフォルトスクリプト

デフォルトでは、WordPress には WordPress 自体が使用するスクリプトの他に多くのスクリプトが含まれています。 一部を以下の表に挙げます。

$handleパラメータの代わりに使用できる名前の詳細なリストについては、ハンドルと WordPress で登録済みのスクリプトのパスを参照してください。


Version 3.5 で、WordPress は縮小されたスクリプトとスタイルの命名規則が変更されました。Version 3.5 以前は、縮小されたスクリプトとスタイルには .js および .css という拡張子がつけられており、縮小されていなかったスクリプトには .dev.js および .dev.css という拡張子がつけられていました。変更後の拡張子は、縮小されたファイルの場合は .min.js および .min.css 、縮小されていないファイルの場合はそれぞれ .js および .css になりました。

名前 ハンドル 必要なファイル *
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 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
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
WordPressから削除されたもの
名前 ハンドル 削除されたバージョン 代替え
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

このリストは完璧ではありません。 登録済みファイルの完璧なリストについては管理UIで $GLOBALS['wp_scripts'] で調べてください。また、登録されたスクリプトは、ページによって変わる場合があります。


*必要なファイルに関する記述は完璧ではありません。

  • 例のように、サイトのフロントエンドで呼び出す場合は、wp_enqueue_scripts アクションフックを使用して関数を呼び出す必要があります。管理画面で呼び出すには、admin_enqueue_scripts /en アクションフックを使用します。ログイン画面では login_enqueue_scripts /en アクションフックを使用します。アクションフックの外側で呼び出すと問題が発生する可能性があります。詳細については ticket #11526 を参照してください。
  • バージョン3.3より前の場合、この関数を wp_head または wp_print_scripts /en アクションフック以降で呼び出すと何の効果もありません。$in_footer パラメータを true にしてあってもファイルをエンキューするには遅すぎるためです。
  • バージョン3.3のとき、この関数をページの途中(wp_footer() テンプレートタグより前)または wp_head アクションフックから呼び出すことができます。このようにするとスクリプトは $in_footer パラメータが true であるかのようにフッターへ入ります。
  • もし、登録済みのハンドルを異なるパラメータを付けて登録またはエンキューしようとすると、新しいパラメータは無視されます。そうするには、wp_deregister_script() を使った後、スクリプトを新しいパラメータを付けて登録してください。
  • ハンドル jquery-ui-core には jQuery UI Effects が含まれません
  • この関数は、現在のテーマが wp_head()wp_footer() を使う前提で正しく動作します。これらの関数を呼び出さない古いテーマでは正しく動作しないかもしれません。昔のテーマをデバッグするとき覚えておくと良いでしょう。
  • 使用: WP_Scripts::add(), WP_Scripts::add_data(), WP_Scripts::enqueue()
  • グローバルの使用: (不明な型) $wp_scripts

更新履歴

  • Since: 2.6 (BackPress version: r16)

ソースファイル

wp_enqueue_script()wp-includes/functions.wp-scripts.php にあります。

リソース

関連資料




関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/wp_enqueue_script最新版との差分