テンプレート階層

前述のとおり、テンプレートファイルは、モジュール式の再利用可能なファイルで、WordPress サイトの Web ページを生成するために使用されます。テンプレートファイルには、ヘッダーやフッターのテンプレートなど、サイトのすべてのページで使用されるものと、特定の条件下でのみ使用されるものがあります。

この記事では、WordPress が個々のページで使用するテンプレートファイルを決定する方法について説明します。既存の WordPress テーマをカスタマイズしたい場合に、どのテンプレートファイルを編集する必要があるかを判断するのに役立ちます。

ヒント：条件付きタグを使って、特定のページでどのテンプレートを読み込むかをコントロールすることもできます。

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 が使用されます。

例えば、ブログの URL が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 のページが生成されるかを表しています。

または対話式バージョンもあります。

テンプレートの階層は図で見るとわかりやすいのですが、以下のセクションでは、いくつかのクエリタイプに対して WordPress からテンプレートファイルが呼び出される順番を説明します。

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

1. home.php
2. index.php

注意: front-page.php が存在する場合は、 home.php テンプレートに優先します。

front-page.php テンプレートファイルはサイトのフロントページの表示に使用されます。フロントページは(上述の)ブログ投稿インデックスか、固定ページを表示します。フロントページのテンプレートは、ブログ投稿インデックス（home.php）のテンプレートよりも優先されます。front-page.php ファイルが存在しない場合、WordPress は 設定 > 表示設定 での設定に応じて home.php または page.php ファイルを使用します。もしこれらのファイルがどちらも存在しない場合は、index.php ファイルを使用します。

1. front-page.php – 設定 > 表示設定 セクションで「フロントページの表示」が「最新の投稿」または「固定ページ」どちらになっている場合でも使われます。
2. home.php – WordPress が front-page.php を見つけられず、且つ「フロントページの表示」セクションで「最新の投稿」が設定されている場合、home.php を参照します。加えて、WordPress は「フロントページの表示」セクションで「投稿ページ」が設定されている場合にもこのファイルを参照します。
3. page.php – 「フロントページの表示」セクションでフロントページが設定されている場合。
4. index.php – 「フロントページの表示」セクションで「最新の投稿」が設定されており、且つ home.php が存在しない場合。またはフロントページが設定されているが page.php が存在しない場合。

このように、WordPressがどのような経路をとるかには多くのルールがあります。上の図を使用することは、WordPress が何を表示するかを特定する最良の方法です。

privacy-policy.php テンプレートファイルは、あなたのサイトのプライバシーポリシーページをレンダリングするために使われます。プライバシーポリシーページのテンプレートは、静的ページ（page.php）のテンプレートよりも優先されます。privacy-policy.php ファイルが存在しない場合、WordPress は利用可能なテンプレートに応じて page.php または singular.php ファイルを使用します。これらのファイルが存在しない場合は、index.phpファイルを使用します。

1. privacy-policy.php – 「設定」→「プライバシー」の「プライバシーポリシーページの変更」で設定したプライバシーポリシーページに使用されます。
2. カスタムテンプレートファイル – ページに割り当てられたページテンプレートです。詳しくは get_page_templates() をご覧ください。
3. page-{slug}.php – ページスラッグが privacy の場合、WordPress は page-privacy.php の使用を検討します。
4. page-{id}.php – ページ ID が 6 の場合、WordPressは page-6.php を使おうとします。
5. page.php
6. singular.php
7. index.php

個別投稿のテンプレートファイルは、1 つの投稿を表示するために使用されます。WordPress では、以下の順で表示されます:

1. single-{post-type}-{slug}.php – まず、WordPress は特定の記事のテンプレートを探します(4.4 以降) 。例えば、投稿タイプが 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. カスタムテンプレートファイル – ページに割り当てられたページテンプレートです。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テンプレートファイルも以下の順で呼び出されます。

1. 404.php
2. index.php

添付ファイルページ（attachment 投稿タイプ）は、以下の順で表示されます。

1. {MIME-type}.php – 任意のMIME タイプ（メディアタイプ） (例: image.php, video.php, pdf.php)。text/plain ならば以下の順で表示されます。
   1. text-plain.php
   2. plain.php
   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

埋め込みテンプレートファイルは、埋め込み対象の記事を表示するために使用されます。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 は embed.php をフォールバックとします。
4. 最終的に、WordPress は自身のテンプレートである wp-includes/theme-compat/embed.php をフォールバックとします。

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

以下は、IDが 6 である “Hello World 😀” という名前のページのテンプレート階層です。

• 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

ここで author-{role}.php を author.php の前に追加するには、’author_template’ テンプレートタイプを使用して実際の階層を操作することができます。これにより、/author/username へのリクエストがあった時 username が編集者の権限を持つ場合に、現在のテーマディレクトリに author-editor.php があれば表示することができます。

function author_role_template( $templates = '' ) { 
    $author = get_queried_object(); 
    $role = $author->roles[0];

    if ( ! is_array( $templates ) && ! empty( $templates ) ) { 
        $templates = locate_template( array( "author-$role.php", $templates ), false ); 
    } elseif ( empty( $templates ) ) { 
        $templates = locate_template( "author-$role.php", false ); 
    } else { 
        $new_template = locate_template( array( "author-$role.php" ) );

        if ( ! empty( $new_template ) ) { 
            array_unshift( $templates, $new_template ); 
        } 
    } 
    return $templates; 
} 

add_filter( 'author_template', 'author_role_template' );

変更履歴:

• アップデート 2022-02-15 この例では、.php ファイルを使用し、ブロックテーマでは .html ファイルを使用するが、テンプレート階層はクラシックテーマとブロックテーマで同じという注釈を追記。

原文: https://developer.wordpress.org/themes/basics/template-hierarchy/
翻訳 GitHub: https://github.com/jawordpressorg/theme-handbook/blob/main/theme/basics/template-hierarchy.md

最終更新日: 2022年10月12日