WordPress 模板部件（Template Parts）完全指南

发布于 作者:

WordPress 模板部件是构建现代块主题的核心组件。简单来说，它们是网站中可重复使用的页面片段——比如页头、页脚或侧边栏。你可以在多个模板中引用同一个部件，这避免了代码重复，也让维护变得更加轻松。比如，当你需要修改整个网站的页脚信息时，只需更新一个模板部件文件，所有使用该部件的页面都会同步生效。

模板部件本质上是一个独立的 HTML 块标记文件，存储在主题的 /parts 目录下。它们不会像模板那样被系统自动加载，而是通过 Template Part 块在父模板中明确引用。更重要的是，你可以通过 WordPress 的可视化编辑器对部件进行修改，并实时预览效果。

从开发者角度看，模板部件不仅提升了代码的组织效率，还为用户提供了灵活的设计自由度。无论你是正在构建自己的一个块主题，还是希望更深入地理解 WordPress 主题架构，掌握模板部件都是必不可少的一环。本文将带你从基础概念到实战技巧，了解这一重要特性。

一、模板部件的工作原理

在 WordPress 主题系统中，模板（Templates）负责搭建页面的大框架，而模板部件（Template Parts）则用来填充框架中的各个功能区。

当用户访问网站时，WordPress 会根据浏览的页面类型选择合适的模板进行加载。然后，模板解析引擎会逐行处理模板文件中的块标记。遇到 Template Part 块时，WordPress 就会到主题的 /parts 文件夹中寻找对应的部件文件进行加载和解析。

Template Part 块在代码中的表现是这样的：

html

<!-- wp:template-part {"slug":"header"} /-->

这个简单的标记告诉 WordPress 去加载 /parts/header.html 文件。

一个典型的模板文件可能会这样引用多个部件：

html

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group -->
<div class="wp-block-group">
	<!-- 这里存放页面主要内容 -->
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

注意上面代码中的 tagName 参数，它指定了部件外层包裹容器的 HTML 标签，比如 header 或 footer。这有助于保持语义化 HTML 结构，对 SEO 和可访问性都有好处。

解析流程是这样的：

  1. 加载 /parts/header.html 并解析其中的所有块
  2. 解析模板中其他独立的块
  3. 加载 /parts/footer.html 并解析其中的所有块
  4. 将终渲染的 HTML 发送给浏览器

二、模板部件的内容构成

与经典主题中的 PHP 模板片段不同，块主题中的模板部件只包含纯粹的块标记（Block Markup）。这意味着每个部件都由嵌套的 HTML 结构和对应的注释标记组成。

下面是一个简单的页脚部件示例，存放于 /parts/footer.html：

html

<!-- wp:group {"align":"wide"} -->
<div class="wp-block-group alignwide">
	<!-- wp:site-title {"level":3} /-->
	
	<!-- wp:paragraph -->
	<p>使用 WordPress 驱动</p>
	<!-- /wp:paragraph -->
	
	<!-- wp:social-links -->
	<ul class="wp-block-social-links">
		<li>社交媒体链接</li>
	</ul>
	<!-- /wp:social-links -->
</div>
<!-- /wp:group -->

这个页脚部件包含了站点标题块、段落块和社交链接块。部件可以很简单，只放一两行文字；也可以非常复杂，包含多个区块嵌套。

对于块标记语法的深入理解，可以参考 WordPress 官方文档中的块编辑器核心概念。

三、如何组织模板部件文件

在块主题中，所有模板部件都必须放在主题根目录下的 /parts 文件夹内。典型的目录结构长这样：

text

parts/
├── comments.html
├── footer.html
├── header.html
└── sidebar.html

WordPress 不支持在 /parts 文件夹内再建子文件夹来组织部件。也就是说，所有部件文件必须平铺在 /parts 目录下，无法像 parts/headers/ 这样的嵌套方式。

如果你使用的是旧版 WordPress，系统也会识别 /block-template-parts 文件夹，但这是为了向下兼容而保留的路径。新主题建议统一使用 /parts 文件夹。

四、创建和构建模板部件

模板部件可以通过两种方式创建：

方法一：手动编写代码

直接在你的代码编辑器中创建 HTML 文件，编写块标记。这种方式适合对代码结构有清晰规划的开发者。

方法二：通过可视化编辑器生成

  • 进入 WordPress 后台，打开「外观 > 编辑器」
  • 在「模板部件」区域点击新建按钮
  • 在可视化编辑器中拖拽添加所需块，定制样式
  • 编辑完成后，复制编辑器中的块标记到对应的 /parts/xxx.html 文件中

推荐先通过编辑器直观地搭建部件，再把代码迁移到主题文件中，后将主题打包分发或部署到生产环境。

五、注册模板部件

为了让模板部件在 WordPress 后台的编辑界面中正常显示并拥有友好的名称，你需要在 theme.json 文件中进行注册。

注册示例（在 theme.json 中）：

json

{
	"version": 2,
	"templateParts": [
		{
			"area": "header",
			"name": "header",
			"title": "页头（默认）"
		},
		{
			"area": "footer",
			"name": "footer",
			"title": "页脚（默认）"
		},
		{
			"area": "uncategorized",
			"name": "sidebar",
			"title": "侧边栏"
		}
	]
}
  • area：指定部件所属的区域（下面会详细说明）
  • name：对应 /parts/ 目录中的文件名，不含 .html 后缀
  • title：在后台界面中显示的名称，支持翻译

注册后，这些部件就会出现在「模板部件」库中，用户可以直接选用和编辑。

六、在后台编辑模板部件

进入「外观 > 编辑器」，在左侧边栏点击「模板部件」，就可以看到所有已注册的部件列表。它们按区域分类排列：

  • 页头（Header）
  • 页脚（Footer）
  • 通用（General）

点击任何一个部件即可进入可视化编辑器，像编辑页面一样拖拽添加或调整块。所有修改都会实时预览。

保存位置说明：

如果你在后台编辑部件并保存，这些更改会存入数据库，覆盖主题文件中的原始版本。这意味着在网页上看到的是数据库版本，而不是 /parts/ 文件夹中的文件版本。

如果你打算把这个主题分享给其他人或用于其他站点，记得把编辑好的块标记代码复制到对应的 /parts/xxx.html 文件中。

七、创建新的模板部件

在「模板部件」面板中，点击「新增」按钮，会弹出一个对话框：

  • 输入部件名称（比如「文章循环」）
  • 选择所属区域（比如「通用」或自定义区域）
  • 点击创建

系统会进入一个全新的编辑界面，你可以在其中自由添加各种块来构建这个新部件。

注意： 通过后台新建的部件默认只保存在数据库中。如需在主题中使用，必须将生成的块标记复制到 /parts/ 目录下的相应文件中，并确保在 theme.json 中完成注册。

八、模板部件区域（Template Part Areas）

模板部件区域是用于对部件进行分类和组织的机制。在后台界面中，部件会按区域分组展示，方便用户查找和管理。

WordPress 内置了三个默认区域：

区域标识显示名称说明
uncategorized通用未分类的部件
header页头通常包含网站标志、导航菜单等
footer页脚通常包含版权信息、友情链接等

注意： 如果你开发的主题有特定的设计需求，可能需要创建自定义区域来更好地组织部件。比如一个「循环」区域，专门存放各种文章列表样式的部件。

九、注册自定义部件区域

你可以通过 default_wp_template_part_areas 过滤器来注册自定义区域。添加以下代码到主题的 functions.php 文件中：

php

add_filter( 'default_wp_template_part_areas', 'mytheme_register_template_part_areas' );

function mytheme_register_template_part_areas( $areas ) {
	$areas[] = array(
		'area'        => 'loop',
		'area_tag'    => 'section',
		'label'       => '循环区域',
		'description' => '存放各种文章循环样式的部件',
		'icon'        => 'layout'
	);
	
	return $areas;
}

每个区域定义包含以下字段：

  • area：区域的标识符（机器名）
  • area_tag：该区域部件默认使用的 HTML 包裹标签，如 section、div、aside 等
  • label：后台显示的名称，支持国际化翻译
  • description：区域功能说明
  • icon：图标标识，目前只有 header、footer 和 sidebar 有专属图标

注册完区域后，就可以在 theme.json 中将特定的部件分配到该区域了：

json

{
	"version": 2,
	"templateParts": [
		{
			"area": "loop",
			"name": "loop-default",
			"title": "循环 - 默认样式"
		},
		{
			"area": "loop",
			"name": "loop-grid",
			"title": "循环 - 网格样式"
		}
	]
}

这样在后台的模板部件面板中，就会看到「循环区域」分组，下面列出了你注册的所有循环部件。

总结

  • 模板部件是 WordPress 块主题中的可复用内容片段，存放于 /parts 文件夹中
  • 通过 Template Part 块在父模板中引用部件，支持设置 slug 和 tagName 属性
  • 部件文件只包含块标记，不包含 PHP 代码
  • 所有部件必须平放在 /parts 目录下，不支持子目录嵌套
  • 建议在 theme.json 中注册所有部件，以获得更好的后台管理体验
  • 通过后台编辑器修改的部件会存入数据库，主题文件中的原始版本不会被自动覆盖
  • 利用自定义区域可以更有效地组织和分类部件，提升用户体验
  • 部件内容的迁移流程：可视化编辑 → 复制标记 → 粘贴到 /parts/xxx.html → 分发主题

掌握模板部件的使用，是构建现代 WordPress 块主题的基础技能之一。它不仅让你的代码更加整洁有序，也为终用户提供了更灵活、更直观的网站定制体验。