6.6. 在 Drupal 中使用模板：了解 Drupal 核心中的模板。

我们已经看到 Drupal 内置了 Twig，并了解了它的使用方式。本文将讲解如何在 Drupal 中使用模板：包括 Drupal 核心 Stable 主题中有哪些模板、如何重写 Stable 模板，以及如何为不同类型的 Drupal 实体自定义模板。

首先，让我们从 Stable 主题 的模板开始，进入该主题的 templates 文件夹：

模板按功能分类存放：

/core/themes/stable/templates/admin — 管理界面模板（如 Views UI、管理页面、消息和报告模板）。
/core/themes/stable/templates/block — 区块模板。
/core/themes/stable/templates/content — 内容模板（节点、评论、分类术语、RSS 元素、搜索结果等）。
/core/themes/stable/templates/content-edit — 编辑表单和过滤器模板。
/core/themes/stable/templates/dataset — 论坛、RSS、表格、列表模板。
/core/themes/stable/templates/field — 不同字段类型的模板。
/core/themes/stable/templates/form — 表单元素模板。
/core/themes/stable/templates/layout — 页面结构模板，如 page.html.twig、区域和主模板 html.html.twig。
/core/themes/stable/templates/misc — 各种辅助模板，如 RSS、RDF 图标、系统消息、进度条等。
/core/themes/stable/templates/navigation — 菜单、书籍（Book 模块）、分页、工具栏、垂直选项卡、面包屑导航模板。
/core/themes/stable/templates/user — 用户页面、用户名、论坛帖子签名模板。
/core/themes/stable/templates/views — Views 模块模板。

如你所见，Stable 主题提供了大量可重写的模板。要重写它们，只需将所需模板复制到你的子主题中并进行修改。建议仅在需要时重写模板，而不是一次性复制全部。

重写内容模板（Template Suggestions）

除了修改现有模板外，你还可以为特定节点、分类术语、区块等创建自定义模板。以下是一些模板重写的示例。

HTML 模板

HTML 模板定义页面的基本结构。

主模板：html.html.twig（路径：core/modules/system/templates/html.html.twig）

可使用以下方式重写：

1. html--internalviewpath.html.twig
2. html--node--id.html.twig
3. html.html.twig

其中 internalviewpath 指的是 Drupal 内部路径，例如 node/15、taxonomy/term/46、user/2 等。

详细文档参见：html.html.twig

页面模板（Page Template）

重写方式：page--[front|internal/path].html.twig

主模板：page.html.twig（路径：core/modules/system/templates/page.html.twig）

页面模板的优先级多样，主页模板优先级最高。主页可在以下路径设置：

/admin/config/system/site-information

请注意：Drupal 使用内部路径，而不是 URL 别名。例如，/news/node-title 实际路径可能为 /node/15。

节点编辑页面（如 http://www.example.com/node/1/edit）可使用以下模板重写：

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

详细文档参见：page.html.twig

区域模板（Regions）

重写方式：region--[region].html.twig

主模板：region.html.twig（路径：core/modules/system/templates/region.html.twig）

当区域内有区块或通过 hook_page_build() 创建的内容时，会使用该模板。区域名称在主题的 .info.yml 文件中定义。

详细文档参见：region.html.twig

区块模板（Blocks）

重写方式：block--[module|delta].html.twig

主模板：block.html.twig（路径：core/modules/block/templates/block.html.twig）

例如：

1. block--module--delta.html.twig
2. block--module.html.twig
3. block.html.twig

其中 module 是生成该区块的模块名称，delta 是该模块内区块的唯一 ID。

例如，block--block--1.html.twig 表示用户通过 Block 模块添加的第一个区块。若你的自定义模块定义了 delta 为 “my-block”，则模板为 block--custom--my-block.html.twig。

对于 Views 模块，模板命名如：block--views-block--front-news-block-1.html.twig。

注意：模板名区分大小写，且下划线 (_) 会替换为连字符 (-)。

文档参见：block.html.twig

内容模板（Nodes）

重写方式：node--[type|nodeid]--[viewmode].html.twig

主模板：node.html.twig（路径：core/modules/node/templates/node.html.twig）

示例：

1. node--nodeid--viewmode.html.twig
2. node--type--viewmode.html.twig
3. node--type.html.twig
4. node.html.twig

其中 viewmode 表示显示模式（Full、Teaser、RSS、Token 等），type 为内容类型（例如 News、Article、Page）。

文档参见：node.html.twig

分类术语模板（Taxonomy Terms）

重写方式：taxonomy-term--[vocabulary-machine-name|tid].html.twig

主模板：taxonomy-term.html.twig（路径：core/modules/taxonomy/templates/taxonomy-term.html.twig）

示例：

1. taxonomy-term--tid.html.twig
2. taxonomy-term--vocabulary-machine-name.html.twig
3. taxonomy-term.html.twig

命名中所有下划线需替换为连字符。

文档参见：taxonomy-term.html.twig

字段模板（Fields）

重写方式：field--[type|name|content-type].html.twig

主模板：field.html.twig（路径：core/modules/system/templates/field.html.twig）

示例：

1. field--field-name--content-type.html.twig
2. field--field-type.html.twig
3. field.html.twig

所有下划线均替换为连字符。

文档参见：field.html.twig

评论模板（Comments）

重写方式：comment--node-[type].html.twig

主模板：comment.html.twig（路径：core/modules/comment/templates/comment.html.twig）

例如，comment--node-article.html.twig 可为文章类型定义专属评论模板。

还可以为评论包裹层定义模板：

重写方式：comment-wrapper--node-[type].html.twig

主模板：comment-wrapper.html.twig（路径：core/modules/comment/templates/comment-wrapper.html.twig）

Views 模板

每个 View 至少使用两个模板：

• views-view.html.twig — 视图整体模板。
• views-view-unformatted.html.twig — 默认显示样式模板。

如果视图显示字段（而非完整实体），可重写 views-view-fields.html.twig。

示例模板命名：

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

论坛模板（Forum）

重写方式：forums--[container|topic]--forumID.html.twig

主模板：forums.html.twig（路径：core/modules/forum/templates/forums.html.twig）

可分别为容器和主题定义模板：

forums--containers--forumID.html.twig  
forums--topics--forumID.html.twig

文档参见：forums.html.twig

维护模式模板（Maintenance Mode）

重写方式：maintenance-page--[offline].html.twig

主模板：maintenance-page.html.twig（路径：core/modules/system/templates/maintenance-page.html.twig）

文档参见：maintenance-page.html.twig

搜索结果模板（Search Results）

重写方式：search-result--[searchType].html.twig

主模板：search-result.html.twig（路径：core/modules/search/templates/search-result.html.twig）

示例：

• 节点搜索：/search/node/Search+Term → search-result--node.html.twig
• 用户搜索：/search/user/bob → search-result--user.html.twig