在 WordPress 中注册自定义模板：theme.json 完全指南

发布于 作者:

本文深入讲解如何在 WordPress 块主题中通过 theme.json 注册自定义模板。你将理解 customTemplates 属性的工作原理、模板文件的存放规则，以及如何为不同文章类型创建专属布局。文章包含完整的代码示例和后台操作截图说明，帮你从零开始掌握自定义模板的注册与构建流程。无论你想创建空白画布模板、带侧边栏的页面，还是为特定内容类型设计独特样式，这份指南都能给你清晰的实现路径。

什么是自定义模板？

在 WordPress 主题开发中，自定义模板指的是你可以为单篇文章、页面或自定义文章类型（CPT）创建独立的布局方案。这些模板注册后，用户在编辑文章时可以直接从侧边栏选择，前端展示就会随之变化。

举个例子，你开发了一个企业官网主题，默认页面带侧边栏。但某些落地页需要全宽展示，这时候注册一个“全宽无侧边栏”模板就派上用场了。用户创建新页面时，只需在模板下拉框中选中它，无需任何代码操作。

需要强调的是，customTemplates 属性仅针对单篇文章/页面/CPT的模板，不是用来注册归档页、搜索页这类模板的。

核心机制：模板如何被识别？

块主题的模板查找逻辑很简单：所有模板文件必须放在主题根目录下的 /templates 文件夹中。你在 theme.json 里注册的模板名称，必须和这个文件夹里的文件名一一对应。

比如你注册了一个 name 为 full-width 的模板，那么主题目录下必须存在 /templates/full-width.html 文件。WordPress 就是通过这个名称匹配来加载对应模板的。

注册模板的完整步骤

一步：创建模板文件

在主题目录下新建文件夹 templates（如果还没有的话），然后创建一个 HTML 文件。假设我们要做一个“内容画布”模板，只显示标题、正文和页脚，适合做 landing page 或产品详情页。

文件名定为：/templates/content-canvas.html

文件内容先留空，后面再填。

二步：在 theme.json 中注册

打开主题根目录的 theme.json 文件（没有就新建一个），加入 customTemplates 数组：

json

{
  "version": 2,
  "customTemplates": [
    {
      "name": "content-canvas",
      "title": "内容画布",
      "postTypes": ["page", "post"]
    }
  ]
}

参数说明：

  • name：模板标识符，必须和文件名一致（不含 .html 后缀）
  • title：后台显示的名称，支持翻译
  • postTypes：可选，指定该模板可用于哪些文章类型。不写的话默认只对页面（page）生效

保存后，去后台编辑任意页面或文章，在右侧面板的“模板”下拉框中就能看到“内容画布”选项了。

三步：构建模板内容

现在来填充 /templates/content-canvas.html 文件。下面是一个简的区块模板代码：

html

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

<!-- wp:group {"tagName":"main","layout":{"type":"default"}} -->
<main class="wp-block-group">
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

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

这段代码做了三件事：

  1. 引入主题的头部模板部分（header）
  2. 用 <main> 标签包裹文章内容区块（post-content）
  3. 引入主题的底部模板部分（footer）

注意：template-part 引用的是 /parts 文件夹里的模板部件。确保你的主题里有 header.html 和 footer.html 这两个文件，否则这段代码无法正常工作。

保存后，进入站点编辑器（外观 > 编辑器），在模板列表里就能看到“内容画布”了。点击即可预览和进一步定制。

进阶用法与注意事项

1. 模板的继承与覆盖

WordPress 的模板查找有优先级顺序：用户自定义模板 > 主题模板 > 父主题模板（子主题环境下）。如果你在子主题中注册了同名模板，它会覆盖父主题的版本。

2. 限定特定文章类型

如果你的主题注册了“图书”这种自定义文章类型（book），想为它单独做一个展示模板：

json

{
  "name": "book-detail",
  "title": "图书详情页",
  "postTypes": ["book"]
}

这样该模板只会在编辑图书文章时出现，不会干扰其他内容类型。

3. 不要过度提供模板

虽然你可以注册无数个模板，但从用户体验角度考虑，建议控制在 3-5 个以内。模板太多会让用户困惑，反而降低使用体验。常见做法是提供：默认模板、全宽模板、无侧边栏模板、带侧边栏模板，基本就够用了。

4. 模板文件必须是 HTML

块主题的模板文件统一使用 .html 格式，而不是 .php。这是块主题和经典主题的关键区别之一。如果你习惯写 PHP 模板，需要切换到区块语法。

5. 后台编辑体验

注册完成后，用户在编辑文章时切换模板，编辑器内的预览会实时反映模板的布局变化。但要注意，某些模板部件（如自定义页眉）可能需要保存后才能在前端正确显示。

实际开发中的典型场景

场景一：产品落地页

为 product 这个 CPT 注册一个“沉浸式展示”模板，隐藏导航菜单，只保留产品大图、描述和购买按钮。这个模板适合用在电商站点的爆款产品页面。

场景二：博客长文模板

为 post 注册一个“宽版阅读”模板，内容区宽度提升到 1200px，左右留白减少，适合技术博客或深度评测类文章。

场景三：公司介绍页

为 page 注册一个“团队介绍”模板，预设团队成员的展示布局，让编辑人员直接套用，保持页面风格统一。

总结

注册自定义模板的关键流程可以概括为三步：创建 HTML 文件 → 在 theme.json 中声明 → 编写区块代码。这套机制让主题开发者能够为不同内容类型提供差异化的展示方案，同时将选择权交给用户，真正实现了前后端分离的灵活性。

掌握 customTemplates 的使用，是进阶 WordPress 块主题开发的必经之路。从今天起，不妨在下一个主题项目中尝试注册一两个自定义模板，感受这种开发模式带来的与自由。