首頁 > Drupal目錄 > Twig 模板命名慣例

Twig 模板命名慣例

Tag :

Twig, Template

Written by Shiuan on 22 November 2023

本篇資料來源：Twig Template naming conventions | Twig in Drupal | Drupal Wiki guide on Drupal.org

翻譯：Shiuan Huang

Drupal 根據特定的命名慣例載入模板。這使我們能夠透過將它們添加到您的佈景主題並給予特定名稱來寫入模板。

在添加模板後，您必須重建快取，以便 Drupal 發現您的新模板。

您可以偵錯 Twig 模板，以找出用於輸出任何給定元素的標記的模板。有關 Twig 偵錯的更多訊息，請參閱關於 Twig 偵錯。

此頁面列出了用於基本HTML結構、頁面、區域、區塊、節點、欄位和其他核心組件的慣例。重要的是知道，可以使用 function hook_theme_suggestions_HOOK_alter 創建自定義模板名稱建議。

HTML（<head> 模板）

HTML 模板提供了 HTML 頁面的基本結構標記，包括 <head>、<title> 和 <body> 標籤。

基本模板：html.html.twig（基本位置：core/modules/system/templates/html.html.twig）

以下是一些覆蓋基本模板的示例：

html--[internalviewpath].html.twig
html--node--[nodeid].html.twig
html.html.twig

詳情請參閱html.html.twig API documentation

頁面模板

模式：page--[front|internal/path].html.twig
基本模板：page.html.twig（基本位置：core/modules/system/templates/page.html.twig）

建議的選項很多。首頁具有優先權。其餘基於當前頁面的內部路徑。可以在「管理 > 設定 > 系統 > 網站資訊」中設置首頁。首頁模板是page--front.html.twig。

不要將內部路徑與路徑別名混淆，後者未予考慮。

建議的模板文件列表按照內部路徑的特定順序排列。對於當前路徑的每個元素，都提出一個建議，雖然數字元素不會傳遞到後續的建議。例如以下建議：

page--node--edit.html.twig
page--node--1.html.twig
page--node.html.twig
page.html.twig

詳情請參閱 page.html.twig API documentation。另請參閱本文下方的維護頁面模板。

區域

模式：region--[region].html.twig
基本模板：region.html.twig（基本位置：core/modules/system/templates/region.html.twig）

當頁面區域具有內容時，將使用區域模板，內容來自區塊系統或像 hook_page_top() 或 hook_page_bottom() 這樣的功能。可能的區域名稱由主題的 .info.yml file 決定。

詳情請參閱 region.html.twig API documentation

區塊

模式：block--[module|--[delta].html.twig
基本模板：block.html.twig（基本位置：core/modules/block/templates/block.html.twig）

block--[module]--[delta].html.twig
block--[module].html.twig
block.html.twig

"module" 是模組的名稱，而 "delta" 是由模組分配的區塊的內部ID。

例如，"block--block--1.html.twig" 將用於從區塊管理畫面中，第一個由用戶在模組中提交的區塊，其ID為1。 Region-specific block templates are not available in Drupal 8.

如果您創建一個名稱為 "custom" 的自定義模組的區塊，並且 delta 為 "my-block"，則佈景主題掛鈎建議將被稱為 "block--custom--my-block.html.twig"。

另外舉一個使用 Views 的例子，如果您有一個由 Views 創建的區塊，視圖名稱為 "front_news"，顯示ID為 "block_1"，則佈景主題掛鈎建議將是：block--views-block--front-news-block-1.html.twig（請注意，當顯示ID或視圖名稱中包含底線時，您必須將它們轉換為單個破折號）。

請注意，在這種上下文中，模組名稱是區分大小寫的。例如，如果您的模組名稱為 'MyModule'，則該模組最常見的佈景主題掛鈎建議將是 "block--MyModule.html.twig"。

詳情請參閱block.html.twig API documentation

佈局建構器 (Layout builder) 區塊

對於通過佈局建構器創建的「自定義區塊」，以下是模板命名的建議：

block--inline-block--[block-type].html.twig
block--inline-block.html.twig
block--[block-type].html.twig
block--layout-builder.html.twig
block.html.twig

節點

模式：node--[content-type|nodeid]--[viewmode].html.twig
基本模板：node.html.twig（基本位置：core/modules/node/templates/node.html.twig）

基於這些因素，建議使用佈景主題掛鈎，按照最具體到最不具體模板的順序列出。Drupal 將使用找到的最具體模板：

node--[nodeid]--[viewmode].html.twig
node--[nodeid].html.twig
node--[content-type]--[viewmode].html.twig
node--[content-type].html.twig
node--[viewmode].html.twig
node.html.twig

請注意，內容類型的機器名稱中的底線 ( _ ) 請以破折號 ( - ) 取代。

詳情請參閱node.html.twig API documentation

分類術語

模式：taxonomy-term--[vocabulary-machine-name|tid].html.twig
基本模板：taxonomy-term.html.twig（基本位置：core/modules/taxonomy/templates/taxonomy-term.html.twig）

基於這些因素，建議使用佈景主題掛鈎，按照從最具體模板到最不具體模板的順序列出。Drupal將使用找到的最具體模板：

taxonomy-term--[tid].html.twig
taxonomy-term--[vocabulary-machine-name].html.twig
taxonomy-term.html.twig

請注意，underscores的機器名稱中的底線 ( _ ) 請以破折號 ( - ) 取代。

詳情請參閱taxonomy-term.html.twig API documentation

欄位

模式：field--[[type|name]|[entity-type]--[field-name|content-type]].html.twig
基本模板：field.html.twig（基本位置：core/modules/system/templates/field.html.twig）

基於這些因素，建議使用佈景主題掛鈎，按照從最具體模板到最不具體模板的順序列出。Drupal將使用找到的最具體模板：

field--node--[field-name]--[content-type].html.twig
field--node--[field-name].html.twig
field--node--[content-type].html.twig
field--[field-name].html.twig
field--[field-type].html.twig
field.html.twig

請注意，欄位的機器名稱中的底線 ( _ ) 請以破折號 ( - ) 取代。同時，請記得在自定義欄位名稱中包含 "field-"，例如：field--field-phone.html.twig。

詳情請參閱field.html.twig API documentation

評論包裝(wrappers)

模式：field--node--[comment-field-name]--[content-type].html.twig
基本模板：field--comment.html.twig

論壇(Forums)

模式：forums--[[container|topic]--forumID].html.twig
基本模板：forums.html.twig（基本位置：core/modules/forum/templates/forums.html.twig）

基於這些因素，建議使用佈景主題掛鈎，按照從最具體模板到最不具體模板的順序列出。Drupal將使用找到的最具體模板：

對於論壇內容：

forums--containers--[forumid].html.twig
forums--[forumid].html.twig
forums--containers.html.twig
forums.html.twig

對於論壇主題：

forums--topics--[forumid].html.twig
forums--[forumid].html.twig
forums--topics.html.twig
forums.html.twig

詳情請參閱API documentation for forums.html.twig

維護頁面

模式：maintenance-page--[offline].html.twig
基本模板：maintenance-page.html.twig（基本位置：core/modules/system/templates/maintenance-page.html.twig）

當數據庫失敗時使用。在不顯示錯誤消息的情況下呈現更友好的頁面。首先必須正確設置主題化維護頁面Theming the maintenance page。

詳情請參閱maintenance-page.html.twig API documentation

請注意，當數據庫無法使用時，無法呈現 maintenance-page--offline.html.twig 文件。問題正在持續追蹤中：#2720109: maintenance-page--offline.html.twig is not picked up when system is offline

搜尋結果

模式：search-result--[search-type].html.twig
基本模板：search-result.html.twig（基本位置：core/modules/search/templates/search-result.html.twig）

search-result.html.twig 是單個搜尋結果的默認包裝 (wrapper)。根據搜尋類型，提出了不同的建議。例如，"example.com/search/node/Search+Term" 將使用 "search-result--node.html.twig"。與之相對比的是，"example.com/search/user/bob" 將使用 "search-result--user.html.twig"。模組可以擴展搜尋類型，添加更多與其類型相關的建議。

詳情請參閱search-result.html.twig API documentation

Views

所有 Views 模板都可以使用各種名稱進行寫入，包括 Views 本身、Views 的顯示ID、Views 的顯示類型，或者這些元素的某種組合。

對於每個 Views，將使用至少兩個模板。第一個用於所有 Views：views-view.html.twig.

第二個模板由 Views 選擇的樣式決定。請注意，Views 的某些方面也可能更改使用的樣式；例如，提供摘要檢視的參數可能將樣式更改為其中一種特殊的摘要樣式。

所有 Views 默認的樣式是views-view-unformatted.html.twig.

然後，許多樣式將實際顯示每一行的內容委派給行樣式；默認的行樣式是 views-view-fields.html.twig

模式：

views-view--[viewid]--[view-display-id].html.twig
views-view--[viewid]--[view-display-type].html.twig
views-view--[view-display-type].html.twig
views-view--[viewid].html.twig
views-view.html.twig

基本模板：views-view.html.twig（基本位置：core/themes/stable/templates/views/views-view.html.twig）

例如，如果我們想要覆蓋 "views-view.html.twig" 模板，則以下模板名稱是有效的：

views-view--[viewid]--[view-display-id].html.twig
views-view--[viewid]--page.html.twig
views-view--block.html.twig
views-view--[viewid].html.twig
views-view.html.twig

views-view-field.html.twig 等模式會以 Views 的欄位ID（如替換模式中的）為後綴，以在 Views 中顯示單個欄位：

views-view-field--[viewid]--[view-display-id]--[fieldid].html.twig
views-view-field--[viewid]--page--[fieldid].html.twig
views-view-field--block--[fieldid].html.twig
views-view-field--[fieldid].html.twig
views-view-field.html.twig

以下是在以下情況下將嘗試的所有模板的示例：

名稱為 foobar 的 Views。樣式：未格式化。行樣式：字段。顯示：頁面。

views-view--foobar--page.html.twig
views-view--page.html.twig
views-view--foobar.html.twig
views-view.html.twig
views-view-unformatted--foobar--page.html.twig
views-view-unformatted--page.html.twig
views-view-unformatted--foobar.html.twig
views-view-unformatted.html.twig
views-view-field--foobar--page.html.twig
views-view-field--page.html.twig
views-view-field--foobar.html.twig
views-view-field.html.twig

媒體(Media)

基本模板：media.html.twig（基本位置：core/modules/media/templates/media.html.twig）。

media--source-[source-id].html.twig
media--[media-type]--[view-mode].html.twig
media--[media-type].html.twig
media--[view-mode].html.twig
media.html.twig

流行的貢獻模組

以下是流行的貢獻模組其模板命名的文件鏈結

Paragraphs

返回Drupal

首頁 > Drupal > Twig 模板命名慣例