logo

额外区块类型 (EBT) - 全新的布局构建器体验❗

额外区块类型 (EBT) - 样式化、可定制的区块类型：幻灯片、标签页、卡片、手风琴等更多类型。内置背景、DOM Box、JavaScript 插件的设置。立即体验布局构建的未来。

演示 EBT 模块 下载 EBT 模块

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验

额外段落类型 (EPT) - 类似的基于 Paragraph 的模块集合。

演示 EPT 模块 滚动

滚动
  1. 首页
  2. Drupal 文档
  3. Drupal 8 主题化
  4. Drupal 8 中的 Twig

Twig 模板命名约定

03/10/2025, by Ivan

Menu

Drupal 会根据特定的命名约定加载模板。这使你能够通过将模板添加到主题并赋予它们特定的名称来覆盖模板。

在添加模板之后，你必须重建缓存，这样 Drupal 才能识别你的新模板。

你可以调试 Twig 模板以确定哪些模板用于渲染标记。更多关于 Twig 调试的信息。

本页列出了用于 HTML 基础结构、页面、区域、区块、节点、字段和其他核心组件的命名约定。（需要注意的是，你可以使用 hook_theme_suggestions_HOOK_alter 函数 创建自定义模板命名建议。）

HTML (<head> 模板)

HTML 模板为 HTML 页面的基本结构提供标记，包括 <head>、<title> 和 <body> 标签。

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

以下是一些覆盖基础模板的示例：

  1. html--[internalviewpath].html.twig
  2. html--node--[nodeid].html.twig
  3. html.html.twig

参见 html.html.twig API 文档。

Page 模板

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

建议非常多。主页具有最高优先级。其他页面的模板基于页面的内部路径。在管理后台的 Administration > Configuration > System > Site information 可以设置主页 (http://example.com/admin/config/system/site-information)。主页模板是 page--front.html.twig。
注意：内部路径与别名不同，路径别名不会被考虑。

模板文件建议列表根据内部路径的具体程度排序。当前路径的每个部分都会生成一个建议，但数字部分不会传递到后续建议中。例如，「http://www.example.com/node/1/edit」将生成以下建议：

  1. page--node--edit.html.twig
  2. page--node--1.html.twig
  3. page--node.html.twig
  4. page.html.twig

参见 page.html.twig API 文档。另见下方 维护页面模板。

Regions

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

当页面区域有内容时（来自区块系统或函数，如 hook_page_top() 或 hook_page_bottom()），区域模板会被使用。区域名称在主题的 .info.yml 文件中定义。

参见 region.html.twig API 文档。

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” 是模块为区块分配的内部标识符。

例如，「block--block--1.html.twig」用于用户添加的第一个区块，因为它由 block 模块创建并分配了 ID 1。在 Drupal 8 中不支持特定于区域的区块模板。

如果你有一个由名为 “custom” 的自定义模块创建的区块，并且 delta 是 “my-block”，模板命名将是 block--custom--my-block.html.twig。

另一个示例：如果你有一个由 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 文档。

Nodes

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

模板建议基于以下因素，按具体程度从高到低排列。Drupal 将使用它找到的最具体的模板：

  1. node--[nodeid]--[viewmode].html.twig
  2. node--[nodeid].html.twig
  3. node--[content-type]--[viewmode].html.twig
  4. node--[content-type].html.twig
  5. node--[viewmode].html.twig
  6. node.html.twig

注意：内容类型的机器名称中的下划线 (_) 会被替换为短横线 (-)。

参见 node.html.twig API 文档。

Taxonomy terms

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

模板建议基于以下因素，按具体程度从高到低排列。Drupal 将使用它找到的最具体的模板：

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

注意：词汇表机器名称中的下划线会被替换为短横线。

参见 taxonomy-term.html.twig API 文档。

Fields

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

模板建议基于以下因素，按具体程度从高到低排列。Drupal 将使用它找到的最具体的模板：

  1. field--node--[field-name]--[content-type].html.twig
  2. field--node--[field-name].html.twig
  3. field--node--[content-type].html.twig
  4. field--[field-name].html.twig
  5. field--[field-type].html.twig
  6. field.html.twig

注意：字段机器名称中的下划线 (_) 会被替换为短横线 (-)。还要记得在自定义字段名称中包含 “field-”，例如：field--field-phone.html.twig。

参见 field.html.twig API 文档。

Comments

模板: comment--[comment-field-name]--[node-type].html.twig
基础模板: comment.html.twig（位置：core/modules/comment/templates/comment.html.twig）

支持为不同类型节点的评论创建 comment--[comment-field-name]--[node-type].html.twig 文件。例如，文章类型节点上的评论模板是 comment--field-comments--article.html.twig。

参见 comment.html.twig API 文档。

评论包装器

模板: 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 将使用它找到的最具体的模板：

对于论坛容器：

  1. forums--containers--[forumid].html.twig
  2. forums--[forumid].html.twig
  3. forums--containers.html.twig
  4. forums.html.twig

对于论坛主题：

  1. forums--topics--[forumid].html.twig
  2. forums--[forumid].html.twig
  3. forums--topics.html.twig
  4. forums.html.twig

参见 forums.html.twig API 文档。

Maintenance page

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

当数据库故障时使用。适用于显示无错误消息的友好页面。维护页面主题必须首先正确配置。

参见 maintenance-page.html.twig API 文档。

注意：当数据库不可用时，maintenance-page--offline.html.twig 文件当前不会被使用。相关问题：#2720109: maintenance-page--offline.html.twig 在系统离线时未被发现。

Search result

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

search-result.html.twig 是单个搜索结果的默认包装器。根据搜索类型会有不同的模板建议。例如，「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 文档。

Views

所有 Views 模板都可以使用视图、视图显示 ID、显示类型或它们的组合来覆盖。

每个视图至少使用两个模板。第一个是所有视图通用的：views-view.html.twig。

第二个模板由为视图选择的样式决定。注意：某些视图的设置也可能改变样式，例如汇总视图参数可能会切换到特殊的汇总样式。

所有视图的默认样式是 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 的模板会在名称中添加字段 ID，用于覆盖视图中某个字段的渲染：

  • 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，样式：unformatted，行样式：fields，显示类型：page。

  • 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-fields--foobar--page.html.twig
  • views-view-fields--page.html.twig
  • views-view-fields--foobar.html.twig
  • views-view-fields.html.twig