WordPress 主题模板：从入门到精通

发布于 作者:

理解 WordPress 模板系统是主题开发的核心。本文将用通俗易懂的方式，带你搞懂模板的工作原理、文件结构、创建方法，以及如何通过模板定制网站的每一个页面。无论你是想开发自己的主题，还是想更好地控制网站外观，这篇指南都能帮你快速上手。

模板到底是什么？

简单说，模板就是决定网页“哪里放什么”的蓝图。它告诉 WordPress：头部放什么、主要内容在哪里、底部展示哪些信息。

在经典主题中，模板由 PHP 代码和 HTML 混写而成。但在块主题（Block Theme）中，模板全部由块（Block）的 HTML 标记组成。这也是为什么块主题的模板文件后缀是 .html，而不是 .php。

WordPress 根据访问的 URL 判断用户想看什么类型的页面，然后按优先级顺序寻找匹配的模板：

  1. 数据库中用户保存的模板（优先级高）
  2. 子主题的 /templates 文件夹
  3. 当前主题的 /templates 文件夹

找到模板后，WordPress 解析其中的块标记，生成终的 HTML 输出给浏览器。

模板文件里有什么？

一个典型的模板文件包含三类东西：

  • 块标记：例如 <!-- wp:group -->...<!-- /wp:group -->
  • 模板部件引用：例如 <!-- wp:template-part {"slug":"header"} /-->
  • 块模式引用：例如 <!-- wp:pattern {"slug":"theme-name/hidden-404"} /-->

看一个真实的例子（来自 Twenty Twenty-Three 主题的 404.html）：

html

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:pattern {"slug":"twentytwentythree/hidden-404"} /-->
</main>
<!-- /wp:group -->

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

这个模板做了三件事：

  1. 引入头部模板部件
  2. 在主体区域嵌入一个名为 hidden-404 的块模式
  3. 引入尾部模板部件

重点：你的模板文件必须全部由合法的块标记组成，否则 WordPress 无法正确解析。

模板文件放在哪？

块主题的模板必须放在主题根目录下的 /templates 文件夹中。结构如下：

text

templates/
├── 404.html        （404错误页）
├── archive.html    （归档页，如分类、标签）
├── author.html     （作者页）
├── home.html       （首页）
├── index.html      （通用回退模板，**必须存在**）
├── page.html       （单页面）
└── singular.html   （单篇文章/页面/自定义文章类型的回退模板）

index.html 是关键文件——它的存在告诉 WordPress “这是一个块主题”。没有它，WordPress 会认为你的主题是经典主题。

如何创建和编辑模板？

在后台编辑

  1. 进入 WordPress 后台，点击 外观 → 编辑器
  2. 在左侧边栏点击 模板，可以看到当前所有模板列表
  3. 点击任意模板即可在可视化编辑器中修改

注意：在编辑器里保存的模板会被存到数据库中，会覆盖主题文件夹里的同名模板。如果你要分发主题给别人，别忘了把修改后的块标记复制回主题的 /templates 文件夹里。

新建模板

点击模板列表上方的“+添加新模板”按钮，会弹出一个对话框。你可以选择：

  • 标准模板：按模板层级命名（如 archive.html）
  • 自定义模板：任意名称，可分配给特定页面

新建的模板同样默认保存在数据库。要分发，需要在 /templates 下创建对应的 .html 文件并复制内容。

自定义模板（Custom Templates）

自定义模板就是你可以手动分配给特定文章、页面或自定义文章类型的模板。在文章编辑器的右侧边栏，找到“模板”选项，就能选择你创建的自定义模板。

两种使用场景：

  1. 简单场景：比如一个“联系我们”页面，用不同的布局展示
  2. 复杂场景：比如一个新闻杂志风格的首页，包含多个文章查询区块

在主题中分发自定义模板需要两步：

  1. 在 /templates 文件夹中创建模板文件（文件名任意，只要不与标准模板名冲突）
  2. 在 theme.json 中注册这个模板

注册示例（在 theme.json 的 "templates" 字段中）：

json

{
	"templates": [
		{
			"name": "full-width",
			"title": "全宽页面",
			"postTypes": ["page"]
		}
	]
}

务必注意：自定义模板中如果要显示文章或页面内容，必须包含文章内容块（Post Content block），否则页面正文不会显示。