使用 Twig 模板
Drupal 允許我們寫入用於生成 HTML 標記的所有模板，以便可以完全控制顯示為自訂主題輸出的標記。有各種模板涵蓋每個頁面所需的元素，從高層次的 HTML 到小的欄位。
寫入模板
我們可以透過將符合特定命名慣例的模板加入到主題文件夾來寫入 Drupal 核心模板或貢獻模組的模板。
要寫入模板，我們需要：
- 找到要寫入的模板
- 從其基本位置將模板文件複製到主題文件夾中
- 根據命名慣例重新命名模板，以便針對模板使用特定的子集（可選擇不做）
- 修改模板以滿足我們的需求
一旦將模板文件複製到主題中並清除緩存，Drupal 將開始使用您的模板文件版本，而不是基本版本 (base version)。我們可以使用 Twig 偵錯工具 (debugging tools) 查看使用的模板頁面的任何部分
獲取更具體的Twig建議
如果您想對元素進行更改，但僅限於某些地方，並且需要針對表單和元素（例如按鍵、輸入欄位、標籤等）提供更具體的模板建議，您可以使用這些模組：
- Formdazzle!
還有一個名為 Themable forms 的模組，不過它可能會被遷到另一個模組並且被棄用，詳見＃3057386：合併到 Twig 模板建議器
佈景主題掛鈎建議
有時您可能想要對模板文件進行更改，但僅對其使用的某些地方進行更改。一個常見的例子是僅對特定類型的節點進行更改模板文件節點。Drupal的佈景主題允許我們透過遵循特定的命名慣例來針對模板文件的特定用法。在呈現文章節點時，Drupal首先尋找 node--article.html.twig 模板文件，如果存在則使用它。如果不存在，Drupal 將回退到默認的 node.html.twig 模板。Drupal 確定模板文件可能使用的名稱的過程稱為佈景主題掛鈎建議。
佈景主題掛鈎建議允許您在主題中針對具有特定命名慣例的模板文件實施有針對性的寫入。
來自核心、模組、主題引擎和佈景主題的所有層面都可以提供建議。您可以使用以下掛鈎添加或修改建議：
hook_theme_suggestions_HOOK(array $variables)
hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
為了獲得最佳效果，這裡有一些提示。$suggestions 陣列元素應僅使用 underscores，而不是 hyphens。識別所需的佈景主題掛鈎（Twig 偵錯工具模式將在瀏覽器 HTML 源代碼中顯示此訊息）。然後僅使用該字串 (string) 加上兩個underscores，然後是您的其他自定義語句。例如，如果佈景主題掛鈎被稱為'bob'，在YOURTHEME.theme文件中：
function YOURTHEME_theme_suggestions_bob_alter(array &$suggestions, array $variables, $hook) {
$element = $variables['element'];
$settings = $element['#settings'];
if (!empty($settings['field_name'])) {
$suggestions[] = 'bob__' . strtr($settings['field_name'], '-', '_');
}
}
使用 strtr 函數清除每個 hyphens 並將其替換為 underscores。如果使用 $suggestions[] = 'bobstring__' .，那麼 Twig 模板可能不會加載，因為在double-underscores之前，佈景主題掛鈎不是獨立的。
背景資訊
您可以將這些建議視為命名提示，告訴系統根據正確的情況進行挑選和選擇。
模板建議是透過佈景主題掛鈎建議設定的，這些掛鈎可以進行修改。這些掛鈎允許任何模組或主題提供替代主題的函數或模板建議名稱，並重新排序或刪除由 hook_theme_suggestions_HOOK() 或提供此掛鈎先前呼叫的建議。
Drupal 如何基於路徑確定頁面佈景主題掛鈎建議
以下是基於 theme_get_suggestions() 函數的另一種解釋：
對於頁面給定可能的模板列表是由 Drupal 透過 theme_get_suggestions() 函數生成的，該函數由 system_theme_suggestions_page() 函數呼叫用。
頁面的 Drupal 路徑首先被化整為組件。如上所述，Drupal 路徑不是其別名的任何一個：對於一個頁面，只有唯一一個的 Drupal 路徑。
接下來，將前綴設定為"page"。然後，對於每個組件，按照以下邏輯進行操作：
如果組件是一個數字，將前綴加上"__%"添加到建議列表中
無論組件是否為數字，都將前綴加上"__"添加到建議列表中
如果組件不是一個數字，將組件加上"__"作為前綴
在編列完組件列表後，如果頁面是前台頁面（通過"Administration > Configuration > System > Site information."設置），則將 "page__front" 添加到建議列表中。
請注意，最終為了將建議轉換為實際文件名稱，"__"被轉換為"--"，並將 ".html.twig" 添加到建議中。因此，對於 node/1/edit，我們得到以下建議列表：
page.html.twig（這是最常見的建議）
page--node.html.twig（並且前綴設置為 page__node）
page--node--%.html.twig
page--node--1.html.twig（前綴未更改，因為組件是一個數字）
page--node--edit.html.twig（並且前綴設置為 page__node__edit）
page--front.html.twig（僅當 node/1/edit 是前台頁面時）
在實際呈現頁面時，將檢查最後一個建議。如果存在，則使用該建議。否則，將檢查上一個建議，以此類推。當然，如果沒有任何覆蓋建議存在，page.html.twig 將是最終建議。這也解釋了為什麼 page--front.html.twig （如果存在）將覆蓋對前台頁面的任何其他建議：它始終是指定為前台頁面的最後一個建議。
與Drupal 7的區別
在 Drupal 7 中，為了修改模板建議，我們在處理函數中修改 $variables['theme_hook_suggestion'] 和 $variables['theme_hook_suggestions']，以引入佈景主題建議。自 Drupal 8 以來，現在模組和佈景主題在它們自己的專用掛鈎中定義和修改佈景主題建議。
更多訊息
更新頁面：主題建議的新掛鈎
使用 Twig 模板
Drupal 允許我們寫入用於生成 HTML 標記的所有模板，以便可以完全控制顯示為自訂主題輸出的標記。有各種模板涵蓋每個頁面所需的元素，從高層次的 HTML 到小的欄位。
寫入模板
我們可以透過將符合特定命名慣例的模板加入到主題文件夾來寫入 Drupal 核心模板或貢獻模組的模板。
要寫入模板，我們需要：
- 找到要寫入的模板
- 從其基本位置將模板文件複製到主題文件夾中
- 根據命名慣例重新命名模板，以便針對模板使用特定的子集（可選擇不做）
- 修改模板以滿足我們的需求
一旦將模板文件複製到主題中並清除緩存，Drupal 將開始使用您的模板文件版本，而不是基本版本 (base version)。我們可以使用 Twig 偵錯工具 (debugging tools) 查看使用的模板頁面的任何部分
獲取更具體的Twig建議
如果您想對元素進行更改，但僅限於某些地方，並且需要針對表單和元素（例如按鍵、輸入欄位、標籤等）提供更具體的模板建議，您可以使用這些模組：
- Formdazzle!
還有一個名為 Themable forms 的模組，不過它可能會被遷到另一個模組並且被棄用，詳見＃3057386：合併到 Twig 模板建議器
佈景主題掛鈎建議
有時您可能想要對模板文件進行更改，但僅對其使用的某些地方進行更改。一個常見的例子是僅對特定類型的節點進行更改模板文件節點。Drupal的佈景主題允許我們透過遵循特定的命名慣例來針對模板文件的特定用法。在呈現文章節點時，Drupal首先尋找 node--article.html.twig 模板文件，如果存在則使用它。如果不存在，Drupal 將回退到默認的 node.html.twig 模板。Drupal 確定模板文件可能使用的名稱的過程稱為佈景主題掛鈎建議。
佈景主題掛鈎建議允許您在主題中針對具有特定命名慣例的模板文件實施有針對性的寫入。
來自核心、模組、主題引擎和佈景主題的所有層面都可以提供建議。您可以使用以下掛鈎添加或修改建議：
hook_theme_suggestions_HOOK(array $variables)
hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
為了獲得最佳效果，這裡有一些提示。$suggestions 陣列元素應僅使用 underscores，而不是 hyphens。識別所需的佈景主題掛鈎（Twig 偵錯工具模式將在瀏覽器 HTML 源代碼中顯示此訊息）。然後僅使用該字串 (string) 加上兩個underscores，然後是您的其他自定義語句。例如，如果佈景主題掛鈎被稱為'bob'，在YOURTHEME.theme文件中：
function YOURTHEME_theme_suggestions_bob_alter(array &$suggestions, array $variables, $hook) {
$element = $variables['element'];
$settings = $element['#settings'];
if (!empty($settings['field_name'])) {
$suggestions[] = 'bob__' . strtr($settings['field_name'], '-', '_');
}
}
使用 strtr 函數清除每個 hyphens 並將其替換為 underscores。如果使用 $suggestions[] = 'bobstring__' .，那麼 Twig 模板可能不會加載，因為在double-underscores之前，佈景主題掛鈎不是獨立的。
背景資訊
您可以將這些建議視為命名提示，告訴系統根據正確的情況進行挑選和選擇。
模板建議是透過佈景主題掛鈎建議設定的，這些掛鈎可以進行修改。這些掛鈎允許任何模組或主題提供替代主題的函數或模板建議名稱，並重新排序或刪除由 hook_theme_suggestions_HOOK() 或提供此掛鈎先前呼叫的建議。
Drupal 如何基於路徑確定頁面佈景主題掛鈎建議
以下是基於 theme_get_suggestions() 函數的另一種解釋：
對於頁面給定可能的模板列表是由 Drupal 透過 theme_get_suggestions() 函數生成的，該函數由 system_theme_suggestions_page() 函數呼叫用。
頁面的 Drupal 路徑首先被化整為組件。如上所述，Drupal 路徑不是其別名的任何一個：對於一個頁面，只有唯一一個的 Drupal 路徑。
接下來，將前綴設定為"page"。然後，對於每個組件，按照以下邏輯進行操作：
如果組件是一個數字，將前綴加上"__%"添加到建議列表中
無論組件是否為數字，都將前綴加上"__"添加到建議列表中
如果組件不是一個數字，將組件加上"__"作為前綴
在編列完組件列表後，如果頁面是前台頁面（通過"Administration > Configuration > System > Site information."設置），則將 "page__front" 添加到建議列表中。
請注意，最終為了將建議轉換為實際文件名稱，"__"被轉換為"--"，並將 ".html.twig" 添加到建議中。因此，對於 node/1/edit，我們得到以下建議列表：
page.html.twig（這是最常見的建議）
page--node.html.twig（並且前綴設置為 page__node）
page--node--%.html.twig
page--node--1.html.twig（前綴未更改，因為組件是一個數字）
page--node--edit.html.twig（並且前綴設置為 page__node__edit）
page--front.html.twig（僅當 node/1/edit 是前台頁面時）
在實際呈現頁面時，將檢查最後一個建議。如果存在，則使用該建議。否則，將檢查上一個建議，以此類推。當然，如果沒有任何覆蓋建議存在，page.html.twig 將是最終建議。這也解釋了為什麼 page--front.html.twig （如果存在）將覆蓋對前台頁面的任何其他建議：它始終是指定為前台頁面的最後一個建議。
與Drupal 7的區別
在 Drupal 7 中，為了修改模板建議，我們在處理函數中修改 $variables['theme_hook_suggestion'] 和 $variables['theme_hook_suggestions']，以引入佈景主題建議。自 Drupal 8 以來，現在模組和佈景主題在它們自己的專用掛鈎中定義和修改佈景主題建議。
更多訊息
更新頁面：主題建議的新掛鈎