Template naming conventions

Drupal基于某些命名规则载入模板。 把这些模板加到你的主题并赋予具体的名字可以使你覆写核心模板。

每次覆写一个模板都需要清缓存以便Drupal发现新的模板。

在输出任何元素块时，你都可以调试Twig模板来找出那些模板正在被调用。

该页面列出了基本html结构，page，区域，区块，节点，字段和其他核心组件的模板。

HTML（）

HTML模板提供了基本的HTMl页面结构，包含，和标签。

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

以下是两个覆写基础模板的例子：

1. html--站点路径.html.twig
2. html--node--节点id.html.twig

具体可以查看html.html.twig的API文档。

Page 模板

规则：page--[front|内部路径].html.twig

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

该规则不是单一的。首页优先，而后是内部路径。首页设置是在"管理> 配置> 系统> 站点信息."（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文档.

区域

规则: region--[区域].html.twig

基础模板: region.html.twig (内核位置: core/modules/system/templates/region.html.twig)

区域模板在区域有内容时, 区块系统或者函数如hook_page_build()调用时被使用. 可用的区域名是从主题的.info.yml文件中获取的。

具体查看region.html.twigAPI文档

区块

规则：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

“module”是模块的名字，“delta”是该模块下这个区块的id。

例如，“block--block--1.html.twig”就是在去看管理页面创建的第一个区块的模板，因为它是有block模块创建的并且id为1。指定区域的区块模板在Drupal8中不再适用。

若你有一个自定义模块叫做”custom“，并且模块id是“my-block”，那么模板命名就是“block--custom--my-block.html.twig”。

下面是对视图的例子。若你有一个视图区块，视图名字是“front_news”，显示id是“block_1”，那么模板命名就是：block--views-block--front-news-block-1.html.twig （注意视图或者显示id里的下划线“_”都需要转成中横杠“-”）。

请注意本文中模块名字是区分大小写的，如果你的模块名字叫做“MyModule”，那么模板的命名一般就会成这样“block--MyModule.html.twig”。

节点

规则：node-[type|nodeid].html.twig

基础模板：node.html.twig（核心位置：core/modules/node/templates/node.html.twig）

主题模板是基于以下因素, 从详细到次要， Drupal会使用最具体的模板：

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

要注意的是内容类型的机器名下划线需用连字符替换。

更多具体信息可以查看Drupal node.html.twig API文档。

分类

规则：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

要注意的是词汇的机器名下划线需用连字符替换。

更多具体信息可以查看Drupal taxonomy-term.html.twig API文档。

字段

规则: field--[type|name[--content-type]|content-type].html.twig

基础模板: field.html.twig (核心位置: core/modules/system/templates/field.html.twig)

主题模板是基于以下因素, 从详细到次要， Drupal会使用最具体的模板：

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

要注意的是字段的机器名下划线需用连字符替换。不要忘了加上“field-”， 例如field--field-phone.html.twig。

评论

规则: comment--node-[type].html.twig

基础模板: comment.html.twig (核心位置: core/modules/comment/template/comment.html.twig）

comment--node-[type].html.twig支持站点内特定内容类型的评论模板。例如，对文章类型的节点评论的模板就是“comment--node-article.html.twig”。

对与包装后的评论模板，类似规则如下：

规则: comment-wrapper--node-[type].html.twig

基础模板: comment-wrapper.html.twig

论坛

规则: 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

论坛主题：

1. forums--topics--forumID.html.twig
2. forums--forumID.html.twig
3. forums--topics.html.twig

维护页面

规则: maintenance-page--[offline].html.twig

基础模板: maintenance-page.html.twig (内核位置: core/modules/system/templates/maintenance-page.html.twig)

数据库挂的时候会应用这个模板，提供了一个友好错误提示页面，不过前提是正确安装。

搜索结果

规则: search-result--[searchType].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”。模块可以通过扩展搜索类型增加更多的模板。

---

以下是英文原文，可对照阅读：

Last updated May 7, 2015. Created on October 11, 2014. Edited by rteijeiro, tebb, NonProfit, kiwad. You can edit this page, too.

Drupal loads templates based on certain naming conventions. This allows you to override templates by adding them to your theme and giving them specific names.

After replacing a template you must rebuild the cache in order for Drupal to discover your new template.

You can debug Twig templates to figure out which templates are being used to output the markup for any given element.

This page lists the conventions used for the base html structure, the page, regions, blocks, nodes, fields, and other core components.

HTML ( template)

The HTML template provides markup for the basic structure of the HTML-page including the , and tags.

Base template: html.html.twig (base location: core/modules/system/templates/html.html.twig)

The following are some examples of how you may override the base template:

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

See the html.html.twig API documentation.

Page template

Pattern: page--[front|internal/path].html.twig Base template: page.html.twig (base location: core/modules/system/templates/page.html.twig)

The suggestions are numerous. The front page takes precedence. The rest are based on the internal path of the current page. The front page can be set at "Administration > Configuration > System > Site information." (http://example.com/admin/config/system/site-information). The front page template is page--front.html.twig. Do not confuse the internal path with path aliases, which are not accounted for.

The list of suggested template files is in order of specificity based on internal paths. One suggestion is made for every element of the current path, though numeric elements are not carried to subsequent suggestions. For example, "http://www.example.com/node/1/edit" would result in the following suggestions:

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

See the page.html.twig API documentation.

Regions

Pattern: region--[region].html.twig Base template: region.html.twig (base location: core/modules/system/templates/region.html.twig)

The region template is used when a page region has content, either from the Block system or a function like hook_page_build(). Possible region names are determined by the theme's .info.yml file.

See the API documentation for region.html.twig

Blocks

Pattern: block--[module|-delta]].html.twig Base template: block.html.twig (base location: core/modules/block/templates/block.html.twig)

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

"module" being the name of the module and "delta", the internal id assigned to the block by the module.

For example, "block--block--1.html.twig" would be used for the first user-submitted block added from the block administration screen since it was created by the block module with the id of 1. Region-specific block templates are not available in Drupal 8.

If you had a block created by a custom module called "custom" and a delta of "my-block", the theme hook suggestion would be called "block--custom--my-block.html.twig."

Also one more example with Views, if you have a block created by views with a view name "front_news" and display id "block_1" then the theme hook suggestion would be: block--views-block--front-news-block-1.html.twig (notice, when you have underscores in a display id or in a view name - you have to transform them in to a single dash)

Be aware that module names are case sensitive in this context. For instance if your module is called 'MyModule', the most general theme hook suggestion for this module would be "block--MyModule.html.twig."

Nodes

Pattern: node--[type|nodeid].html.twig Base template: node.html.twig (base location: core/modules/node/templates/node.html.twig)

Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:

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

Note that underscores in a content type's machine name are replaced by hyphens.

See node.html.twig in the Drupal API documentation for more information.

Taxonomy terms

Pattern: taxonomy-term--[vocabulary-machine-name|tid].html.twig Base template: taxonomy-term.html.twig (base location: core/modules/taxonomy/templates/taxonomy-term.html.twig)

Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:

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

Note that underscores in a vocabulary's machine name are replaced by hyphens.

See the API documentation for taxonomy-term.html.twig.

Fields

Pattern: field--[type|name[--content-type]|content-type].html.twig Base template: field.html.twig (base location: core/modules/system/templates/field.html.twig)

Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:

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

Note that underscores in a Field's machine name are replaced by hyphens. Also remember to include "field-" in custom field names, e.g: field--field-phone.html.twig.

Comments

Pattern: comment--node-[type].html.twig Base template: comment.html.twig (base location: core/modules/comment/template/comment.html.twig

Support was added to create comment--node-type.html.twig files, to format comments of a certain node type differently than other comments in the site. For example, a comment made on an article-type node would be "comment--node-article.html.twig".

Pattern: comment-wrapper--node-[type].html.twig Base template: comment-wrapper.html.twig

Similar to the above but for the wrapper template.

Forums

Pattern: forums--[[container|topic]--forumID].html.twig Base template: forums.html.twig (base location: core/modules/forum/templates/forums.html.twig)

Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:

For forum containers:

1. forums--containers--forumID.html.twig
2. forums--forumID.html.twig
3. forums--containers.html.twig

For forum topics:

1. forums--topics--forumID.html.twig
2. forums--forumID.html.twig
3. forums--topics.html.twig

Maintenance page

Pattern: maintenance-page--[offline].html.twig Base template: maintenance-page.html.twig (base location: core/modules/system/templates/maintenance-page.html.twig)

This applies when the database fails. Useful for presenting a friendlier page without error messages. Theming the maintenance page must be properly setup first.

Search result

Pattern: search-result--[searchType].html.twig Base template: search-result.html.twig (base location: core/modules/search/templates/search-result.html.twig)

search-result.html.twig is the default wrapper for individual search results. Depending on type of search different suggestions are made. For example, "example.com/search/node/Search+Term" would result in "search-result--node.html.twig" being used. Compare that with "example.com/search/user/bob" resulting in "search-result--user.html.twig". Modules can extend search types adding more suggestions of their type.