官方模板層次結構與加載順序 - WordPress開發

如上所述，??模板文件??是模塊化的，可重用的文件，用于在WordPress網站上生成網頁。某些模板文件（例如頁眉和頁腳模板）用于您網站的所有頁面，而其他模板文件僅在特定條件下使用。

本文介紹了WordPress如何確定在各個頁面上使用哪些模板文件。如果要自定義現有的WordPress主題，它將幫助您確定需要編輯哪個模板文件。

• 原文來源：wordpress文檔

提示：

您還可以使用條件標簽來控制在特定頁面上加載的模板。

模板文件層次結構

概述

WordPress使用查詢字符串來決定應該使用哪個模板或模板集來顯示頁面。查詢字符串是包含在網站每個部分的鏈接中的信息。它出現在初始問號之后，可能包含許多由＆符號分隔的參數。

簡而言之，WordPress向下搜索模板層次結構，直到找到匹配的模板文件。要確定要使用的模板文件，WordPress：

1. 將每個查詢字符串與查詢類型匹配，以決定請求哪個頁面（例如，搜索頁面，類別頁面等）;
2. 按模板層次結構確定的順序選擇模板;
3. 在當前主題的目錄中查找具有特定名稱的模板文件，并使用層次結構指定的第一個匹配模板文件。

除基本index.php模板文件外，您可以選擇是否要實現特定模板文件。

如果WordPress找不到具有匹配名稱的模板文件，它將跳轉到層次結構中的下一個文件。如果WordPress找不到任何匹配的模板文件，index.php將使用主題的文件。

示例

如果您的博客位于，http://example.com/blog/并且訪問者點擊指向類別頁面的鏈接，例如??http://example.com/blog/category/your-cat/，WordPress會在當前主題的目錄中查找與該類別的ID匹配的模板文件，以生成正確的頁面。更具體地說，WordPress遵循以下過程：

1. 在當前主題的目錄中查找與類別的slug匹配的模板文件。如果類別slug是“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模板文件是用來使您的網站的頭版，頭版是否顯示該博客文章的索引（上述）或靜態頁面。首頁模板優先于博客文章index（home.php）模板。如果該front-page.php文件不存在，WordPress將使用home.php或page.php文件，具體取決于設置→閱讀中的設置。如果這兩個文件都不存在，它將使用該index.php文件。

1. front-page.php?- 用于設置→閱讀的首頁顯示部分中設置的“?您的最新帖子?”或“?靜態頁面?”?。
2. home.php?- 如果WordPress無法找到，??front-page.php并且在首頁顯示部分設置了“?您的最新帖子?”?，則會查找。此外，當在首頁顯示部分設置帖子頁面時，WordPress將查找此文件。home.php
3. page.php?- 在首頁顯示部分設置“?首頁?”時。
4. index.php?-當“?你最新的帖子?”被設置在頭版顯示部分，但??home.php不存在或??在頭版設置，但page.php不存在。

正如您所看到的，WordPress采用的路徑有很多規則。使用上面的圖表是確定WordPress將顯示的最佳方式。

單帖

單個帖子模板文件用于呈現單個帖子。WordPress使用以下路徑：

1. single-{post-type}-{slug}.php?- （從4.4開始）首先，WordPress會查找特定帖子的模板。例如，如果帖子類型是product和post slug是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。

單頁

用于呈現靜態頁面的模板文件（pagepost-type）。請注意，與其他post-types不同，pageWordPress特殊并使用以下路徑：

1. custom template file?-?分配給頁面的頁面模板。見get_page_templates()。
2. page-{slug}.php?- 如果頁面slug是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?- 如果類別的slug是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?- 如果標簽的slug是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

附件

呈現附件頁面（attachmentpost-type）使用以下路徑：

1. {MIME-type}.php-可以是任何的MIME類型（例如：??image.php，video.php，pdf.php）。對于text/plain，使用以下路徑（按順序）：
2. text-plain.php
3. plain.php
4. text.php
5. attachment.php
6. single-attachment-{slug}.php?- 例如，如果附件slug是holiday，WordPress會尋找single-attachment-holiday.php。
7. single-attachment.php
8. single.php
9. singular.php
10. 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回歸嵌入.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

相同的行為適用于post slugs，term names和author nicenames。

過濾層次結構

WordPress模板系統允許您過濾層次結構。這意味著您可以在層次結構的特定點插入和更改內容。過濾器（位于get_query_template()函數中）使用此過濾器名稱："{$type}_template"其中$type是模板類型。

以下是模板層次結構中所有可用過濾器的列表：

• embed_template
• 404_template
• search_template
• frontpage_template
• home_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' );