WordPress 主题开发：theme.json 中注册模板部件完全指南

发布于2024年1月8日2026年7月30日作者:XQcms

在 WordPress 主题开发中，你是否曾经在多个页面文件里复制粘贴相同的头部或底部代码？当需要修改时，又不得不逐个文件去更新，既繁琐又容易遗漏。模板部件（Template Parts）正是为了解决这个问题而生——它让你能把重复的页面片段抽取成独立文件，在需要的地方随时调用。而通过 theme.json 文件注册这些模板部件，还能让它们在站点编辑器中拥有更友好的名称和分类，大提升开发体验。本文将基于 WordPress 官方文档，为你拆解从注册到调用的完整流程，让初学者也能轻松掌握这一核心技能。

什么是模板部件？

简单说，模板部件就是可以从主题主模板中分离出来的页面片段。它遵守编程中的 DRY 原则（Don‘t Repeat Yourself，即不要重复自己），把那些在多个模板中重复出现的部分，比如网站头部、底部、侧边栏，打包成独立文件，需要时直接插入即可。

比如你的主题有首页、文章页、页面模板，它们都需要显示相同的站点标题和导航菜单。如果没有模板部件，你就得在每个模板文件里重复写这段代码。而有了模板部件，只需维护一个 header.html 文件，所有引用它的模板都会自动同步更新。

为什么要在 theme.json 中注册模板部件？

虽然技术上讲，你不注册也能使用模板部件，但在 theme.json 中注册有实实在在的好处：

界面友好：给模板部件设置一个可翻译的标题，在站点编辑器中显示更美观
分类清晰：将部件归入特定区域（如页头、页脚），在编辑器里的体验更流畅
兼容性更好：插件、样式变体和子主题可以更规范地获取或过滤这些部件的元数据

如何注册模板部件？

在 theme.json 文件中，通过 templateParts 属性传入一个对象数组。每个对象包含三个字段：

字段	说明	可选值
`name`	模板部件文件名（不含 `.html` 后缀）	自定义
`title`	显示在后台的标题，支持翻译	自定义
`area`	部件所属区域	`header`、`footer`、`uncategorized` 或自定义

注意：WordPress 默认在主题的 /parts 文件夹中查找模板部件文件。如果你注册了一个 name 为 example 的部件，那么主题目录下必须存在 /parts/example.html 文件。

基础示例

常见的注册是站点头部和底部。先在主题的 /parts 文件夹下创建 header.html 和 footer.html 两个文件（空的也行，稍后填充内容），然后在 theme.json 中这样写：

json

{
    "version": 2,
    "templateParts": [
        {
            "area": "header",
            "name": "header",
            "title": "页头"
        },
        {
            "area": "footer",
            "name": "footer",
            "title": "页脚"
        }
    ]
}

这里 area 和 name 的值恰好相同，看起来有点让人困惑。其实很多主题开发者习惯把模板部件命名为 site-header 和 site-footer 来区分，你可以按自己喜好来。

模板部件放在哪里？

所有模板部件文件统一放在主题的 /parts 文件夹中。WordPress 也兼容旧式的 /template-parts 文件夹，但建议使用 /parts 以保持与现代主题开发规范一致。

填充内容示例

在 /parts/header.html 中放入以下代码，它构建了一个包含站点标题和导航菜单的页头：

html

<!-- wp:group {"style":{"spacing":{"padding":{"top":"2rem","bottom":"2rem","right":"2rem","left":"2rem"}}},"layout":{"type":"default"}} -->
<div class="wp-block-group" style="padding-top:2rem;padding-right:2rem;padding-bottom:2rem;padding-left:2rem">
    <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
    <div class="wp-block-group">
        <!-- wp:site-title /-->
        <!-- wp:navigation {"icon":"menu","layout":{"type":"flex","setCascadingProperties":true,"justifyContent":"right"}} /-->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->

在 /parts/footer.html 中放入：

html

<!-- wp:group {"style":{"spacing":{"padding":{"top":"2rem","right":"2rem","bottom":"2rem","left":"2rem"}}}} -->
<div class="wp-block-group" style="padding-top:2rem;padding-right:2rem;padding-bottom:2rem;padding-left:2rem">
    <!-- wp:group {"align":"wide","style":{"spacing":{"blockGap":"0"}},"layout":{"type":"flex","orientation":"vertical","justifyContent":"center"}} -->
    <div class="wp-block-group alignwide">
        <!-- wp:site-title {"level":0,"isLink":false,"className":"is-style-normalize"} /-->
        <!-- wp:paragraph -->
        <p>Powered by WordPress.</p>
        <!-- /wp:paragraph -->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->

保存后，进入 WordPress 后台的 外观 → 编辑器，在 模板部件 面板中就能看到刚刚注册的页头和页脚了。

如何在模板中引用模板部件？

注册和创建好模板部件后，它们并不会自动出现在网站上。你需要在顶层模板（比如 index.html、single.html 等）中显式引用它们，使用 wp:template-part 块：

html

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

<!-- 这里是模板的其他内容 -->

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

slug 参数对应你注册时的 name 值，tagName 则指定渲染时使用的 HTML 标签（如 header、footer、section 等）。

把上述代码添加到 /templates/index.html 文件中，然后去后台的 外观 → 编辑器 → 模板 里打开首页模板，就能看到页头和页脚已经正确加载了。

需要留意的地方

自定义区域名称时，确保在 area 字段中使用一致的字符串，插件或子主题可能会依赖这个值做逻辑处理
模板部件的 title 字段建议使用翻译函数包裹，方便多语言站点使用
修改 /parts/ 下的文件后，如果编辑器没有立即刷新，尝试在站点编辑器中点击“刷新”按钮或重新加载页面
除了标准的 header 和 footer 区域，你还可以创建任意自定义区域，比如 sidebar、cta 等，用来组织不同类型的部件

总结

模板部件是 WordPress 主题开发中实现代码复用的基础工具。通过 theme.json 注册模板部件，你不仅能规范管理这些可复用的页面片段，还能让它们在站点编辑器中拥有清晰的分类和名称，提升团队协作和多语言适配的效率。注册时记得在 /parts 文件夹中创建对应的 .html 文件，并在顶层模板中用 wp:template-part 块引用。掌握这套流程后，你会发现主题的维护变得轻松许多，重复的代码片段不再是你的负担。