URL とディレクトリパス関数

アセットを含める前に、テーマ内で URL とディレクトリパスを取得するために WordPress が提供するユーティリティ関数に慣れておくべきです。アセットを含める際には、常にこれらのヘルパー関数を使用して、URL またはパスが正しいことを確認してください。

主な URL ヘルパー関数の 3 つは次のとおりです:

  • get_stylesheet_uri(): アクティブなテーマの style.css ファイルの URL を返します。
  • get_theme_file_uri( $file ): アクティブなテーマの URL を返し、オプションの $file パラメータを指定できます。子テーマがアクティブでファイルが存在しない場合は、親テーマにフォールバックします。
  • get_parent_theme_file_uri( $file ): 親テーマの URL を返し、オプションの $file パスを指定できます。

アセットに必要なことは少ないディレクトリパスについては、主に 2 つの関数があります:

  • get_theme_file_path( $file ): アクティブなテーマのディレクトリパスを返し、オプションの $file パラメータを指定できます。子テーマがアクティブでファイルが存在しない場合は、親テーマにフォールバックします。
  • get_parent_theme_file_path( $file ): 親テーマのディレクトリパスを返し、オプションの $file パラメータを指定できます。

CSS の含め方

wp_enqueue_style() はスタイルシートをキューに追加するための主な関数で、WordPress にそれを読み込むためのキューに入れたいことを伝えます。この関数は、あなたの functions.php ファイル内のアクションフックコールバック内で使用します。これは カスタム機能 で学びました。特定のシナリオに対してどのアクションフックを使用するかは、次のセクションで学びます。

関数のシグネチャを見てみましょう: 

  1. wp_enqueue_style(
  2.     string $handle,
  3.     string $src           = '',
  4.     string[] $deps        = array(),
  5.     string|bool|null $ver = false,
  6.     string $media         = 'all'
  7. );

これらのパラメータを使用できます:

  • $handle はスタイルシートの一意の名前/ID で、テーマスラッグでプレフィックスを付ける必要があります。
  • $src はスタイルシートのファイル URL です。技術的にはオプションのパラメータですが、特定のスタイルシートを実際に読み込むには必要です。
  • $deps は、スタイルシートが依存している他のスタイルシートハンドルのオプションの配列です。
  • $ver はスタイルシートのバージョン番号を設定し、キャッシュバスティングに使用されます。デフォルトは現在の WordPress バージョンです。
  • $media は、このスタイルシートを読み込むメディアの種類を指定するためのもので、all (デフォルト)、screen、print、または handheld などがあります。

テーマ内の /assets/css/example.css にあるスタイルシートをキューに追加する場合、関数呼び出しは次のようになります: 

  1. wp_enqueue_style(
  2.     'theme-slug-example',
  3.     get_parent_theme_file_uri( 'assets/css/example.css' ),
  4.     array(),
  5.     wp_get_theme()->get( 'Version' ),
  6.     'all'
  7. );

上記のコードは、キャッシュバスティングのためにテーマのバージョン番号を取得するために wp_get_theme() を使用していますが、デフォルトのままにするか、まったく別のものを使用することもできます。

フロントエンドのスタイルシート

ウェブサイトのフロントエンドでスタイルシートを読み込むときは、ほとんどのシナリオで wp_enqueue_scripts フックを使用します。

テーマの style.css ファイルを get_stylesheet_uri() 関数を使用して読み込みたいと仮定しましょう。この場合、次のコードを functions.php ファイルに追加します: 

  1. add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );
  3. function theme_slug_enqueue_styles() {
  4.     wp_enqueue_style(
  5.         'theme-slug-style',
  6.         get_stylesheet_uri()
  7.     );
  8. }

必要に応じて、wp_enqueue_style() 関数に他のパラメータを渡すこともできます。上記のコードは、スタイルシートを読み込むために必要な最小限のものです。

さらに、テーマ内の /assets/css/primary.css にある 2 番目のスタイルシートを読み込みたいと仮定しましょう。この場合、get_parent_theme_file_uri() 関数を使用して正しい URL を取得します。

両方のスタイルシートをキューに追加した場合のコードは次のようになります: 

  1. add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );
  3. function theme_slug_enqueue_styles() {
  4.     wp_enqueue_style(
  5.         'theme-slug-style',
  6.         get_stylesheet_uri()
  7.     );
  9.     wp_enqueue_style(
  10.         'theme-slug-primary',
  11.         get_parent_theme_file_uri( 'assets/css/primary.css' )
  12.     );
  13. }

インラインスタイル

フロントエンドの <head> エリアにインライン CSS を追加する必要がある場合があります。この特定のシナリオには、WordPress に wp_add_inline_style() 関数があります。

関数のシグネチャを見てみましょう: 

  1. wp_add_inline_style(
  2.     string $handle,
  3.     string $data
  4. );

この場合、ページにキューに追加されている既存のスタイルシートのハンドルと一致する $handle パラメータを渡す必要があります。$data パラメータはあなたのカスタム CSS コードです。

前のセクションのコードを拡張して、ボディの背景色を薄い灰色に設定する小さな CSS を追加してみましょう: 

  1. add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_styles' );
  3. function theme_slug_enqueue_styles() {
  4.     wp_enqueue_style(
  5.         'theme-slug-style',
  6.         get_stylesheet_uri()
  7.     );
  9.     wp_enqueue_style(
  10.         'theme-slug-primary',
  11.         get_parent_theme_file_uri( 'assets/css/primary.css' )
  12.     );
  14.     wp_add_inline_style(
  15.         'theme-slug-primary',
  16.         'body { background: #eee; }'
  17.     );
  18. }

wp_add_inline_style() 関数呼び出しでは、既存の theme-slug-primary ハンドルを使用してインラインスタイルを追加しています。

エディタースタイルシート

フロントエンドにカスタム CSS を持つテーマを作成する場合、カスタムスタイルがエディターにも表示されることをほぼ常に望むでしょう。これにより、サイト全体で一貫したユーザーエクスペリエンスが生まれます。しかし、WordPress はエディターにフロントエンドのスタイルシートを自動的に読み込みません。

そのためには、add_editor_style() 関数を使用する必要があります: 

  1. add_editor_style( array|string $stylesheet = 'editor-style.css' );

これは $stylesheet の単一のパラメータを受け入れ、単一のスタイルシートファイル名またはファイル名の配列を指定できます。これらはテーマフォルダーに対して相対的であるか、完全な URL であることができます。

相対 URL を使用する場合、同じファイル名の子テーマ内のファイルが優先されることに注意してください。これが、一般的に完全なスタイルシート URL を使用することが最良のプラクティスである理由です。

このコードスニペットは、アクティブなテーマのメイン style.css ファイルをエディタースタイルとして追加する方法を示しています: 

  1. add_action( 'after_setup_theme', 'theme_slug_setup' );
  3. function theme_slug_setup() {
  4.     add_editor_style( get_stylesheet_uri() );
  5. }

前の例から style.css ファイルと primary.css を両方追加したい場合は、配列として渡すことができます: 

  1. add_action( 'after_setup_theme', 'theme_slug_setup' );
  3. function theme_slug_setup() {
  4.     add_editor_style( array(
  5.         get_stylesheet_uri(),
  6.         get_parent_theme_file_uri( 'assets/css/primary.css' )
  7.     ) );
  8. }

ブロックスタイルシート

WordPress には、エディターとフロントエンドでブロックごとのスタイルシートを読み込むための wp_enqueue_block_style() 関数も含まれています。これは ブロックスタイルシート ドキュメントで詳細に説明されています。

ブロックスタイルシートの高度な探求については、テーマのパフォーマンスを向上させるための theme.json とブロックごとのスタイルの活用 を WordPress 開発者ブログでお読みください。

JavaScript の含め方

スタイルシートと同様に、WordPress には JavaScript ファイルをキューに追加するための主な関数があります: wp_enqueue_script()。この関数も functions.php ファイル内のアクションフックコールバック内で使用します。次のセクションでどのフックを使用するかを学びます。

関数のシグネチャを見てみましょう: 

  1. wp_enqueue_script(
  2.     string $handle,
  3.     string $src           = '',
  4.     string[] $deps        = array(),
  5.     string|bool|null $ver = false,
  6.     array|bool $in_footer = false
  7. );

これらのパラメータを使用できます:

  • $handle: スクリプトの一意の名前/ID で、テーマスラッグでプレフィックスを付ける必要があります。
  • $src: スクリプトのファイル URL です。技術的にはオプションのパラメータですが、特定のスクリプトを実際に読み込むには必要です。
  • $deps: スクリプトが依存している他のスクリプトハンドルのオプションの配列です。
  • $ver: スクリプトのバージョン番号を設定し、キャッシュバスティングに使用されます。デフォルトは現在の WordPress バージョンです。
  • $in_footer: スクリプトをヘッダーまたはフッターに読み込むかどうかを決定します。WordPress 6.3 以降、このパラメータは値の配列を受け入れます:
    • strategy: 'defer' (デフォルト) または 'async' のいずれかを受け入れて、スクリプトの読み込み戦略を設定します。
    • in_footer: スクリプトをヘッダーまたはフッターに読み込むかどうかを決定するブール値です。

テーマ内の /assets/js/example.js にあるスクリプトをキューに追加する場合、関数呼び出しは次のようになります: 

  1. wp_enqueue_script(
  2.     'theme-slug-example',
  3.     get_parent_theme_file_uri( 'assets/js/example.js' ),
  4.     array(),
  5.     wp_get_theme()->get( 'Version' ),
  6.     true
  7. );

フロントエンドの JavaScript

ウェブサイトのフロントエンドでスタイルシートを読み込むときは、ほとんどのシナリオで wp_enqueue_scripts フックを使用します。

テーマ内の assets/js/navigations.js にカスタムナビゲーションスクリプトがあると仮定しましょう。この場合、get_parent_theme_file_uri() 関数を使用して正しい URL を取得します。

スクリプトをキューに追加する際の関数は次のようになります: 

  1. add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_scripts' );
  3. function theme_slug_enqueue_scripts() {
  4.     wp_enqueue_script(
  5.         'theme-slug-navigation',
  6.         get_parent_theme_file_uri( 'assets/js/navigation.js' ),
  7.         array(),
  8.         wp_get_theme()->get( 'Version' ),
  9.         true
  10.     );
  11. }

インライン JavaScript

時には、フロントエンドの <head> エリアにインライン JavaScript を追加したい場合があります。この目的には、WordPress に wp_add_inline_script() 関数があります。

関数のシグネチャを見てみましょう: 

  1. wp_add_inline_script(
  2.     string $handle,
  3.     string $data,
  4.     string $position = 'after'
  5. );

スタイル用の対応物と同様に、これを $handle パラメータを介してキューに追加されたスクリプトに添付する必要があります。セカンダリパラメータ $data は、JavaScript コード自体であるべきです。ここでの違いは、インラインスクリプトを添付されたスクリプトの前または後に配置できるようにする第 3 のパラメータ $position が追加されていることです。

次のコードは、前のセクションのナビゲーションスクリプトにインラインスクリプトを追加する形で構築されています: 

  1. add_action( 'wp_enqueue_scripts', 'theme_slug_enqueue_scripts' );
  3. function theme_slug_enqueue_scripts() {
  4.     wp_enqueue_script(
  5.         'theme-slug-navigation',
  6.         get_parent_theme_file_uri( 'assets/js/navigation.js' ),
  7.         array(),
  8.         wp_get_theme()->get( 'Version' ),
  9.         true
  10.     );
  12.     wp_add_inline_script(
  13.         'theme-slug-navigation',
  14.         'console.log( "Testing" );'
  15.     );
  16. }

wp_add_inline_script() 関数呼び出しでは、既存の theme-slug-navigation ハンドルを使用してインラインスタイルを追加しています。

エディタ JavaScript

ブロックエディター用の JavaScript ファイルを読み込む必要がある場合、enqueue_block_editor_assets フックを使用する必要があります。これは、コンテンツ iframe 内ではなく、管理ページ自体でスクリプトを読み込むためのものです。

エディター用に読み込む必要がある assets/js/editor.js ファイルがあると仮定しましょう。コードは次のようになります: 

  1. add_action( 'enqueue_block_editor_assets', 'theme_slug_enqueue_editor_scripts' );
  3. function theme_slug_enqueue_editor_scripts() {
  4.     wp_enqueue_script(
  5.         'theme-slug-editor',
  6.         get_parent_theme_file_uri( 'assets/js/editor.js' ),
  7.         array(),
  8.         wp_get_theme()->get( 'Version' ),
  9.         true
  10.     );
  11. }

一般的に、テーマはエディター自体のために JavaScript を読み込む必要はありません。しかし、高度なユースケースでは、必要になることがあります。また、@wordpress/scripts パッケージと統合することをお勧めします。これに関する詳細は、ブロックスタイルを超えて、パート 1: テーマでの WordPress スクリプトパッケージの使用 をお読みください。

デフォルトの WordPress スクリプト

WordPress は多くのカスタムおよびサードパーティのスクリプトをバンドルしています。これらのスクリプトのいずれかが必要な場合は、カスタムバージョンを読み込むのではなく、常にこれらのスクリプトを使用するべきです。これにより、プラグインとの競合を回避できます。

一部のスクリプトは wp_enqueue_script() ドキュメント で参照されていますが、そのリストは常に最新であるとは限りません。含まれているファイルの完全なリストは wp-includes/script-loader.php で見つけることができます。

画像の含め方

ブロックテーマでは、パターンを除いて画像を含める必要はあまりありません。これについては、ブロックパターン ドキュメントで詳しく学びます。しかし、テーマ内で画像を参照する方法を簡単に見てみましょう。

assets/img/example.webp に画像ファイルがあると仮定すると、正しい URL を参照するためにこのコードを使用します: 

  1. <img src="<?php echo esc_url( get_parent_theme_file_uri( 'assets/img/example.webp' ) ); ?>" alt="" />

上記の例では get_parent_theme_file_uri() を使用しています。ほとんどの場合、これが正しい関数になります。

ただし、子テーマを構築している場合や、他の子テーマの作成者が画像をオーバーライドできるようにしたい場合は、get_theme_file_uri() を代わりに使用できます: 

  1. <img src="<?php echo esc_url( get_theme_file_uri( 'assets/img/example.webp' ) ); ?>" alt="" />

フォントの含め方

通常、フォントはアセットのドキュメントの下に直接あることが期待されます。しかし、WordPress にはエディターと統合された theme.json ファイルを介してフォントを読み込むための特別な方法があります。このドキュメントは、グローバル設定とスタイルの章の タイポグラフィ ページにあります。