- 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細)
「関数リファレンス/wp enqueue script」の版間の差分
(→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
にあります。
リソース
- Best practice for adding JavaScript code to WordPress plugins
- How To: Load Javascript With Your WordPress Plugin
- How to load JavaScript in WordPress plugins
- Using JavaScript and CSS with your WordPress Plugin
- Using Javascript libraries with your Wordpress plugin or theme
- 5 Tips For Using jQuery with WordPress
- How to Include CSS and JavaScript Conditionally, and Only When Needed by the Posts
- Make Your WordPress Plugins Use a Different Version of a Bundled JavaScript Library Replacing built-in JavaScript libraries is usually a bad idea. Do this only on sites you administer personally.
- How to load JavaScript like a WordPress Master Highly recommended.
- How to disable scripts and styles
- Loading javascript on the frontend with your WordPress plugin
- JavaScript Tips and Tricks for WordPress 3.x
- Developing for WordPress's customized version of ThickBox
- WordPress Script Registration Generator
関連資料
- エンキュー関数:
- スクリプト:wp_register_script(),wp_deregister_script(), wp_enqueue_script(), wp_dequeue_script() /en, wp_script_is() /en, wp_localize_script(), wp_enqueue_media()
- スタイル: wp_register_style(),wp_deregister_style() /en,wp_enqueue_style(),wp_dequeue_style(), wp_style_is() /en
- エンキューアクション:
- フロントエンド: wp_enqueue_scripts /en, wp_print_scripts /en, wp_print_styles /en
- 管理画面: admin_enqueue_scripts /en, admin_print_scripts / en, admin_print_styles /en
- ログイン: login_enqueue_scripts /en
最新英語版: WordPress Codex » Function Reference/wp_enqueue_script (最新版との差分)