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

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

「関数リファレンス/wp enqueue script」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内、 検索
(→‎script.aculo.us に依存するプラグインのスクリプトをリンクする: 和訳しました。)
細 (→‎script.aculo.us ライブラリをリンクする: タイトルに id 属性を付与。)
48行目: 48行目:
 
</pre>
 
</pre>
  
−
=== script.aculo.us ライブラリをリンクする ===
+
=== script.aculo.us ライブラリをリンクする<span id="Link_the_script.aculo.us_Library"></span> ===
  
 
以下は、 ''scriptaculous'' ハンドルで、WordPressによって [[#Default_Scripts_Included_and_Registered_by_WordPress|すでにインクルード、登録されている]] script.aculo.us ライブラリとをリンクさせる基本的な使い方の例です。
 
以下は、 ''scriptaculous'' ハンドルで、WordPressによって [[#Default_Scripts_Included_and_Registered_by_WordPress|すでにインクルード、登録されている]] script.aculo.us ライブラリとをリンクさせる基本的な使い方の例です。

2018年10月1日 (月) 17:02時点における版

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

説明

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

これは 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' );

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

This example links a script only on a specific administration screen, as opposed to the scenario described in the paragraph below the code of the first example. 

<?php
    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() {
        /* Add our plugin submenu and administration screen */
        $page_hook_suffix = add_submenu_page( 'edit.php', // The parent page of this submenu
                                  __( 'My Plugin', 'myPlugin' ), // The submenu title
                                  __( 'My Plugin', 'myPlugin' ), // The screen title
				  'manage_options', // The capability required for access to this submenu
				  'my_plugin-options', // The slug to use in the URL of the screen
                                  'my_plugin_manage_menu' // The function to call to display the screen
                               );

        /*
          * Use the retrieved $page_hook_suffix to hook the function that links our script.
          * This hook invokes the function only on our plugin administration screen,
          * see: http://codex.wordpress.org/Administration_Menus#Page_Hook_Suffix
          */
        add_action('admin_print_scripts-' . $page_hook_suffix, 'my_plugin_admin_scripts');
    }

    function my_plugin_admin_scripts() {
        /* Link our already registered script to a page */
        wp_enqueue_script( 'my-plugin-script' );
    }

    function my_plugin_manage_menu() {
        /* Display our administration screen */
    }
?>

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

Register and enqueue the script in the same callback function with no dependencies, in the footer. See wp_register_script() for details. In this example, google_analytics_object.js is the Google Analytics tracking code (provided by Google) in a file. 

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

/**
 * Register and enqueue a script that does not depend on a JavaScript library.
 */
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 ラッパー

The jQuery library included with WordPress is set to the noConflict() mode (see wp-includes/js/jquery/jquery.js). This is to prevent compatibility problems with other JavaScript libraries that WordPress can link.

In the noConflict() mode, the global $ shortcut for jQuery is not available, so you can still use: 

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

but the following will either throw an error, or use the $ shortcut as assigned by other library. 

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

However, if you really like the short $ instead of jQuery, you can use the following wrapper around your code: 

jQuery(document).ready(function($) {
    // Inside of this function, $() will work as an alias for jQuery()
    // and other libraries also using $ will not be accessible under this shortcut
});

That wrapper will cause your code to be executed when the DOM is fully constructed. If, for some reason, you want your code to execute immediately instead of waiting for the DOM ready event, then you can use this wrapper method instead: 

(function($) {
    // Inside of this function, $() will work as an alias for jQuery()
    // and other libraries also using $ will not be accessible under this shortcut
})(jQuery);

Alternatively, you can always reasign jQuery to another shortcut of your choice and leave the $ shorcut to other libraries: 

var $j = jQuery;

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

By default, WordPress installation includes many popular scripts commonly used by web developers besides the scripts used by WordPress itself. Some of them are listed in the table below.

For a detailed list of names that can be used in place of the $handle parameter, see Handles and Their Script Paths Registered by WordPress.

Note that in Version 3.5, WordPress changed its naming convention for minified scripts and styles. Before, minified scripts and styles had the .js and .css extensions, unminified had .dev.js and .dev.css. However, following the change, the extensions are .min.js and .min.css for minified files, .js and .css for unminified, respectively.

Script Name Handle Needed Dependency *

-

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
Removed from Core
Script Name Handle Removed Version Replaced With
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

The list is far from complete. For a complete list of registered files inspect $GLOBALS['wp_scripts'] in the admin UI. Registered scripts might change per requested page.

* The listed dependencies are not complete.

注

  • The function should be called using the wp_enqueue_scripts action hook if you want to call it on the front-end of the site, like in the examples above. To call it on the administration screens, use the admin_enqueue_scripts action hook. For the login screen, use the login_enqueue_scripts action hook. Calling it outside of an action hook can lead to problems, see the ticket #11526 for details.
  • Prior to Version 3.3, the function will have no effect if it is called using the wp_head or wp_print_scripts action hooks or later, as this is too late to enqueue the files even if the $in_footer parameter is set to true.
  • As of Version 3.3, the function can be called mid-page (before the wp_footer() template tag) or using the wp_head action hook. This will place the script in the footer as if the $in_footer parameter was set to true.
  • If you try to register or enqueue an already registered handle with different parameters, the new parameters will be ignored. Instead, use wp_deregister_script() and register the script again with the new parameters.
  • jQuery UI Effects is not included with the jquery-ui-core handle.
  • This function relies on the use of wp_head() and wp_footer() by the active theme. This means that it may not work with a few very old themes that do not call these functions. This is useful to keep in mind when debugging ancient themes.
  • Uses: WP_Scripts::add(), WP_Scripts::add_data() and WP_Scripts::enqueue().
  • Uses global: (unknown type) $wp_scripts.

更新履歴

  • Since: 2.6 (BackPress version: r16)

ソースファイル

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

リソース

関連資料




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


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

「https://wpdocs.osdn.jp/wiki/index.php?title=関数リファレンス/wp_enqueue_script&oldid=13463」から取得