テンプレートファイルの階層

概要

WordPressは、ページを表示するために使用するテンプレートまたはテンプレートのセットを決定するために、クエリ文字列を使用します。クエリ文字列は、ウェブサイトの各部分へのリンクに含まれる情報です。

簡単に言えば、WordPressはテンプレート階層を下に検索し、一致するテンプレートファイルを見つけるまで続けます。どのテンプレートファイルを使用するかを決定するために、WordPressは次の手順を実行します：

  • 1. 各クエリ文字列をクエリタイプに一致させ、どのページがリクエストされているかを決定します（例えば、検索ページ、カテゴリページなど）；
  • 2. テンプレート階層によって決定された順序でテンプレートを選択します；
  • 3. 現在のテーマのディレクトリ内で特定の名前のテンプレートファイルを探し、階層によって指定された最初の一致するテンプレートファイルを使用します。

基本的なindex.phpテンプレートファイルを除いて、特定のテンプレートファイルを実装するかどうかを選択できます。

これらの例では、PHPファイル拡張子が使用されています。ブロックテーマでは、代わりにHTMLファイルが使用されますが、テンプレート階層は同じです。

WordPressが一致する名前のテンプレートファイルを見つけられない場合、階層内の次のファイルにスキップします。一致するテンプレートファイルが見つからない場合、テーマのindex.phpファイルが使用されます。

子テーマを使用している場合、子テーマに追加したファイルは親テーマの同じファイルを上書きします。例えば、両方のテーマが同じテンプレートcategory.phpを含む場合、子テーマのテンプレートが使用されます。

子テーマがcategory-unicorns.phpのような特定のテンプレートを含み、親テーマがcategory.phpのような優先度の低いテンプレートを含む場合、子テーマのcategory-unicorns.phpが使用されます。

逆に、子テーマがcategory.phpのような一般的なテンプレートのみを含み、親テーマがcategory-unicorns.phpのような特定のテンプレートを含む場合、親のテンプレートcategory-unicorns.phpが使用されます。

例

あなたのブログがhttp://example.com/blog/にあり、訪問者がhttp://example.com/blog/category/your-cat/のようなカテゴリページへのリンクをクリックすると、WordPressはカテゴリのIDに一致するテンプレートファイルを現在のテーマのディレクトリ内で探し、正しいページを生成します。より具体的には、WordPressは次の手順に従います：

  • 1. 現在のテーマのディレクトリ内でカテゴリのスラッグに一致するテンプレートファイルを探します。カテゴリのスラッグが「unicorns」の場合、WordPressはcategory-unicorns.phpという名前のテンプレートファイルを探します。
  • 2. category-unicorns.phpが存在しない場合、カテゴリのIDが4であれば、WordPressはcategory-4.phpという名前のテンプレートファイルを探します。
  • 3. category-4.phpが存在しない場合、WordPressは一般的なカテゴリテンプレートファイルcategory.phpを探します。
  • 4. category.phpが存在しない場合、WordPressは一般的なアーカイブテンプレートarchive.phpを探します。
  • 5. archive.phpも存在しない場合、WordPressはメインテーマのテンプレートファイルindex.phpにフォールバックします。

視覚的概要

以下の図は、WordPressテンプレート階層に基づいてWordPressページを生成するために呼び出されるテンプレートファイルを示しています。

テンプレート階層（Template Hierarchy） - img1

テンプレート階層の詳細

テンプレート階層は図として理解しやすいですが、以下のセクションでは、WordPressがさまざまなクエリタイプのためにテンプレートファイルを呼び出す順序を説明します。

ホームページの表示

デフォルトでは、WordPressはサイトのホームページを最新のブログ投稿を表示するように設定します。このページはブログ投稿インデックスと呼ばれます。また、ブログ投稿を別の静的ページに表示するように設定することもできます。テンプレートファイルhome.phpは、フロントページとして使用される場合でも、別の静的ページとして使用される場合でも、ブログ投稿インデックスをレンダリングするために使用されます。home.phpが存在しない場合、WordPressはindex.phpを使用します。

  • 1. home.php
  • 2. index.php
  2.  <a name="front-page-display"></a>
  4. ### フロントページの表示
  6. `````front-page.php`````テンプレートファイルは、フロントページがブログ投稿インデックス（上記で言及された）または静的ページを表示するかどうかにかかわらず、サイトのフロントページをレンダリングするために使用されます。フロントページテンプレートは、ブログ投稿インデックス（`````home.php`````）テンプレートよりも優先されます。`````front-page.php`````ファイルが存在しない場合、WordPressは設定の「設定 → 読み込み」での設定に応じて`````home.php`````または`````page.php`````ファイルを使用します。どちらのファイルも存在しない場合、`````index.php`````ファイルが使用されます。  
  8. - 1*.* `````front-page.php`````– 「**最新の投稿**」または「**静的ページ**」の両方に使用され、設定の「フロントページの表示」セクションで設定されます。 
  9. - 2*.* `````home.php`````– WordPressが`````front-page.php`````を見つけられず、「**最新の投稿**」が設定されている場合、`````home.php`````を探します。さらに、WordPressは「フロントページの表示」セクションで「投稿ページ」が設定されている場合にもこのファイルを探します。 
  10. - 3*.* `````page.php`````– 「**フロントページ**」が「フロントページの表示」セクションで設定されている場合。 
  11. - 4*.* `````index.php`````– 「**最新の投稿**」が「フロントページの表示」セクションで設定されているが、`````home.php`````が存在しない場合、または「フロントページ」が設定されているが`````page.php`````が存在しない場合。
  13. ご覧のとおり、WordPressが取るパスには多くのルールがあります。上記のチャートを使用することが、WordPressが表示する内容を決定する最良の方法です。  
  14.  <a name="privacy-policy-page-display"></a>
  16. ### プライバシーポリシーページの表示
  18. `````privacy-policy.php`````テンプレートファイルは、サイトのプライバシーポリシーページをレンダリングするために使用されます。プライバシーポリシーページテンプレートは、静的ページ（`````page.php`````）テンプレートよりも優先されます。`````privacy-policy.php`````ファイルが存在しない場合、WordPressは利用可能なテンプレートに応じて`````page.php`````または`````singular.php`````ファイルを使用します。どちらのファイルも存在しない場合、`````index.php`````ファイルが使用されます。  
  20. - 1*.*  `````privacy-policy.php````` – 設定の「プライバシーポリシーページを変更する」セクションで設定されたプライバシーポリシーページに使用されます。 
  21. - 2*.* `````custom template file````` – ページに割り当てられた[ページテンプレート](/read/wordpress/70782ca476a9a738.md)。`````get_page_templates()`````を参照してください。 
  22. - 3*.* `````page-{slug}.php````` – ページのスラッグが`````privacy`````の場合、WordPressは`````page-privacy.php`````を使用しようとします。 
  23. - 4*.* `````page-{id}.php````` – ページIDが6の場合、WordPressは`````page-6.php`````を使用しようとします。 
  24. - 5*.* `````page.php
  • 6. singular.php
  • 7. index.php

単一投稿

単一投稿テンプレートファイルは、単一の投稿をレンダリングするために使用されます。WordPressは次のパスを使用します：

  • 1. single-{post-type}-{slug}.php– (4.4以降) まず、WordPressは特定の投稿のためのテンプレートを探します。例えば、投稿タイプがproductで、投稿スラッグがdmc-12の場合、WordPressはsingle-product-dmc-12.phpを探します。
  • 2. single-{post-type}.php – 投稿タイプがproductの場合、WordPressはsingle-product.phpを探します。
  • 3. single.php – WordPressは次にsingle.phpにフォールバックします。
  • 4. singular.php – 次にsingular.phpにフォールバックします。
  • 5. index.php – 最後に、上記で述べたように、WordPressは最終的にindex.phpにフォールバックします。

単一ページ

静的ページ（page投稿タイプ）をレンダリングするために使用されるテンプレートファイル。その他の投稿タイプとは異なり、pageはWordPressに特有で、次のパスを使用します：

  • 1. custom template file– ページに割り当てられたページテンプレート。get_page_templates()を参照してください。
  • 2. page-{slug}.php– ページのスラッグがrecent-newsの場合、WordPressはpage-recent-news.phpを使用しようとします。
  • 3. page-{id}.php– ページIDが6の場合、WordPressはpage-6.phpを使用しようとします。
  • 4. page.php
  • 5. singular.php
  • 6. index.php

カテゴリ

カテゴリアーカイブインデックスページのレンダリングには、WordPressで次のパスが使用されます：

  • 1. category-{slug}.php– カテゴリのスラッグがnewsの場合、WordPressはcategory-news.phpを探します。
  • 2. category-{id}.php– カテゴリのIDが6の場合、WordPressはcategory-6.phpを探します。
  • 3. category.php
  • 4. archive.php
  • 5. index.php

タグ

タグアーカイブインデックスページを表示するために、WordPressは次のパスを使用します：

  • 1. tag-{slug}.php– タグのスラッグがsometagの場合、WordPressはtag-sometag.phpを探します。
  • 2. tag-{id}.php– タグのIDが6の場合、WordPressはtag-6.phpを探します。
  • 3. tag.php
  • 4. archive.php
  • 5. index.php

カスタム分類

カスタム分類は、やや異なるテンプレートファイルパスを使用します：

  • 1. taxonomy-{taxonomy}-{term}.php– 分類がsometaxで、分類の用語がsometermの場合、WordPressはtaxonomy-sometax-someterm.php.を探します。投稿フォーマットの場合、分類は「post_format」で、用語は「post-format-{format}」です。つまり、リンク投稿フォーマットの場合はtaxonomy-post_format-post-format-link.phpです。
  • 2. taxonomy-{taxonomy}.php– 分類がsometaxの場合、WordPressはtaxonomy-sometax.phpを探します。
  • 3. taxonomy.php
  • 4. archive.php
  • 5. index.php

カスタム投稿タイプ

カスタム投稿タイプは、適切なアーカイブインデックスページをレンダリングするために次のパスを使用します。

  • 1. archive-{post_type}.php– 投稿タイプがproductの場合、WordPressはarchive-product.phpを探します。
  • 2. archive.php
  • 3. index.php

(単一投稿タイプテンプレートをレンダリングするには、上記の単一投稿表示セクションを参照してください。)

著者表示

上記の例に基づいて、著者アーカイブインデックスページのレンダリングはかなり説明的です：

  • 1. author-{nicename}.php– 著者のニックネームがmattの場合、WordPressはauthor-matt.phpを探します。
  • 2. author-{id}.php– 著者のIDが6の場合、WordPressはauthor-6.phpを探します。
  • 3. author.php
  • 4. archive.php
  • 5. index.php

日付

日付ベースのアーカイブインデックスページは、予想通りにレンダリングされます：

  • 1. date.php
  • 2. archive.php
  • 3. index.php

検索結果

検索結果は、他のテンプレートタイプと同じパターンに従います：

  • 1. search.php
  • 2. index.php

404（見つかりません）

同様に、404テンプレートファイルは次の順序で呼び出されます：

  • 1. 404.php
  • 2. index.php

添付ファイル

添付ファイルページ（attachment投稿タイプ）をレンダリングするには、次のパスを使用します：

  • 1. {MIME-type}.php – 任意のMIMEタイプ（例えば：image.php、video.php、pdf.php）である可能性があります。text/plainの場合、次のパスが使用されます（順番に）：
    • 1.1. text-plain.php
    • 1.2. plain.php
    • 1.3. text.php
  • 2. attachment.php
  • 3. single-attachment-{slug}.php– 例えば、添付ファイルのスラッグがholidayの場合、WordPressはsingle-attachment-holiday.phpを探します。
  • 4. single-attachment.php
  • 5. single.php
  • 6. singular.php
  • 7. index.php

WordPress 6.4以降、添付ファイルページは新しいインストールではデフォルトで無効になっています。ユーザーはプラグインを使用してそれらを有効にできますので、テーマをテストして添付ファイルページを表示する際に正しくコンテンツが表示されることを確認することは依然として良いプラクティスです。

埋め込み

埋め込みテンプレートファイルは、埋め込まれている投稿をレンダリングするために使用されます。4.5以降、WordPressは次のパスを使用します：

  • 1. embed-{post-type}-{post_format}.php– まず、WordPressは特定の投稿のためのテンプレートを探します。例えば、投稿タイプがpostで、オーディオフォーマットを持っている場合、WordPressはembed-post-audio.phpを探します。
  • 2. embed-{post-type}.php – 投稿タイプがproductの場合、WordPressはembed-product.phpを探します。
  • 3. embed.php – WordPressは次に埋め込み.phpにフォールバックします。
  • 4. 最後に、WordPressは最終的に自身のwp-includes/theme-compat/embed.phpテンプレートにフォールバックします。

非ASCII文字の処理

WordPress 4.7以降、名前に非ASCII文字を含むテンプレート名の動的部分は、実際にはエンコードされていない形式とエンコードされた形式の両方をサポートします。この順序で使用するものを選択できます。

「Hello World 😀」という名前のページテンプレート階層で、IDが6のページのためのものです：

  • page-hello-world-.php
  • page-hello-world-%f0%9f%98%80.php
  • page-6.php
  • page.php
  • singular.php

同じ動作は、投稿スラッグ、用語名、および著者のニックネームにも適用されます。

フィルタ階層

WordPressのテンプレートシステムは、階層をフィルタリングすることを許可します。これは、階層の特定のポイントで物事を挿入および変更できることを意味します。フィルタ（get_query_template()関数内にある）は、このフィルタ名を使用します："{$type}_template"、ここで$typeはテンプレートタイプです。

テンプレート階層で利用可能なすべてのフィルタのリストは次のとおりです：

  • embed_template
  • 404_template
  • search_template
  • frontpage_template
  • home_template
  • privacypolicy_template
  • taxonomy_template
  • attachment_template
  • single_template
  • page_template
  • singular_template
  • category_template
  • tag_template
  • author_template
  • date_template
  • archive_template
  • index_template

例

例えば、デフォルトの著者階層を考えてみましょう：

  • author-{nicename}.php
  • author-{id}.php
  • author.php
  3. ``````bash
  4. function author_role_template( $templates = '' ) {
  5.     $author = get_queried_object();
  6.     $role   = $author->roles[0];
  8.     if ( ! is_array( $templates ) && ! empty( $templates ) ) {
  9.         $templates = locate_template( array( "author-$role.php", $templates ), false );
  10.     } elseif ( empty( $templates ) ) {
  11.         $templates = locate_template( "author-$role.php", false );
  12.     } else {
  13.         $new_template = locate_template( array( "author-$role.php" ) );
  15.         if ( ! empty( $new_template ) ) {
  16.             array_unshift( $templates, $new_template );
  17.         }
  18.     }
  19.     return $templates;
  20. }
  21. add_filter( 'author_template', 'author_role_template' );
  22. `

変更履歴：

  • 更新 2022-02-15。テンプレート階層がクラシックテーマとブロックテーマで同じであることを説明する通知を追加しましたが、例では.phpファイルを使用し、ブロックテーマでは.htmlファイルを使用します。