EP177. “搭建 Block Theme 骨架：templates 与 WP 核心 Block”

从零搭建一个最小可用的 Block Theme，理解它跟传统主题的本质区别：模板文件里不能直接写 HTML，必须用 WordPress 认识的「区块注释」语法，这样可视化编辑器才能把模板内容解析成一个个可点击编辑的 Block。用 templates/index.html（首页兜底模板）和 templates/single.html（单篇文章模板，命名规则完全沿用传统主题的 single.php 套路）分别验证：① 直接写裸 HTML 会让编辑器报错、Block Theme 名存实亡；② 用官方核心 Block（post-title/post-content/query-loop）可以做到不写一行 PHP 就展示文章标题、正文、近期文章列表；③ 但这些核心 Block 能力有限（查询循环 Block 无法做自定义关联查询/meta 筛选），复杂需求依然要靠自己写的自定义 Block（配合 PHP）来实现——FSE 并不意味着以后完全不用 PHP。

涉及文件

• wp-content/themes/fictional-block-theme/style.css （新建）
• wp-content/themes/fictional-block-theme/index.php （新建，留空）
• wp-content/themes/fictional-block-theme/theme.json （新建，留空，见 EP176 提醒）
• wp-content/themes/fictional-block-theme/templates/index.html （新建）
• wp-content/themes/fictional-block-theme/templates/single.html （新建）

代码实现

style.css（新建，跟传统主题一样，用注释声明主题名）：

/*
 Theme Name: Fictional University Block Theme
*/

index.php（新建，留空文件即可，不需要写任何 PHP 代码）

theme.json（新建，留空文件，见 EP176 提醒）

templates/index.html（新建，用「区块注释」语法而不是裸 HTML）：

<!-- wp:paragraph -->
<p>Hello.</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3 id="welcome-to-our-site">Welcome to our site.</h3>
<!-- /wp:heading -->

templates/single.html（新建，命名规则沿用传统主题的 single.php）：

<!-- wp:paragraph -->
<p>This is a single blog post template screen.</p>
<!-- /wp:paragraph -->

关键改动点：

• Block Theme 依然需要 style.css 和 index.php 这两个文件：style.css 里的主题名注释写法跟传统主题完全一样；index.php 这一讲留空即可（作者提到未来 WordPress 甚至可能彻底取消这个文件的强制要求，但目前还是必须存在）
• templates/ 文件夹是 Block Theme 特有的：模板文件不再放在主题根目录（像传统主题的 index.php/single.php），而是统一放进这个子文件夹，文件扩展名也从 .php 变成 .html
• 裸 HTML 会破坏 Block Theme：如果直接在 index.html 里写 <p>Hello there!</p> 这种普通 HTML（不带区块注释），前台其实还是能正常显示文字，但后台可视化编辑器打开这个模板时会报错「无法预览」——因为编辑器需要靠特定格式的 HTML 注释来识别「这一段内容是哪种 Block」，纯 HTML 编辑器认不出来，等于表面能用、实际上把 FSE 最大的卖点（可视化编辑）废掉了
• 正确写法：<!-- wp:区块名 {可选的JSON参数} -->...内容...<!-- /wp:区块名 -->——这是 Gutenberg 定义的「区块语法」，本质上还是普通 HTML 注释包裹普通 HTML，但 WordPress 编辑器能解析这种固定格式、知道每一段对应哪个 Block、该用什么设置面板去编辑它
• 实践经验：与其手写区块注释，更推荐直接在可视化编辑器里操作、再把结果复制回模板文件——比如给标题加个 id、设置 {"level":3} 这种参数手写容易出错，这一讲演示的做法是：在「外观 → 编辑器」里正常用点击/拖拽的方式编辑这个模板（跟编辑普通文章一样的体验），存下来后，可以从数据库的 wp_posts.post_content 字段直接复制出对应内容，或者用编辑器右上角「⋮ → 导出」下载一份 zip、里面就有对应格式的模板文件内容，粘贴回自己维护的 .html 模板文件里
• 模板文件是「安全的原始版本」，编辑器里的修改是「运行时的自定义层」：只要模板文件本身没变，不管在后台编辑器里怎么改乱，随时可以在「模板」列表点击某个模板旁边的图标、选「清除自定义项」，一键恢复成 .html 文件里写的内容——这也是为什么把关键版本保留在文件里（而不是只依赖编辑器里的修改）更保险
• 文件命名规则完全沿用传统主题的经验：templates/index.html 是兜底的默认模板（对应传统主题的 index.php）；templates/single.html 是单篇文章模板（对应 single.php）；同理还会有 archive.html、page.html，自定义文章类型也是 single-{文章类型}.html 这种命名规则，跟传统主题几乎是 1:1 对应，之前的经验基本都能直接复用
• WordPress 官方核心 Block 能覆盖不少基础的动态需求，不用写 PHP：
  • post-title：输出当前文章的标题（等同于传统主题里的 the_title()）
  • post-content：输出当前文章的正文（等同于 the_content()）
  • query-loop：一个内建的「查询循环」Block，可以配置查询的文章类型、排序方式、每页几条，内部嵌套一个 post-template 子 Block（决定每篇文章要展示哪些信息，比如标题+日期+摘要），效果类似一个简化版的 WP_Query 循环
• query-loop 的能力上限很明显：设置面板里只能选文章类型、排序方式、按分类筛选，没有办法处理「关联查询」「按自定义 meta 字段筛选」这类复杂需求——比如这门课在传统主题章节写过的「只显示活动日期晚于今天的近期活动」这种查询（按 meta 值筛选、而不是按文章发布日期排序），query-loop 完全做不到，这种场景依然要靠自己写 PHP 自定义 Block 来实现
• FSE/Block Theme 不代表以后不用 PHP 了：即使全部用 WordPress 核心 Block 搭建页面，底层依然 100% 是 PHP 在运作——比如 post-title 这个核心 Block，源码就在 WordPress 安装目录的 wp-includes/blocks/post-title.php 里，内部还是老老实实调用 get_the_title() 这类标准 PHP 函数、决定该用 <h1> 还是 <h2>、要不要包一层链接——核心 Block 只是把这些逻辑封装好了，不是什么新技术魔法
• 官方 2022 默认主题为什么几乎不用自定义 PHP：因为它的所有页面需求，全部用官方核心 Block 就能满足，没有任何自定义查询/关联/复杂输出的需要——如果一个网站的需求恰好也是这样（更像纯粹的排版设计工具而不是内容管理系统），可以全用核心 Block；但如果像 Fictional University 这样有自定义文章类型关系、自定义 meta 查询的真实项目，就还是要靠自己写的自定义 Block（配合 PHP）来实现，这正是这一章接下来要学的内容

[截图：前台单篇文章页面仅由 post-title/post-content 核心 Block 渲染出的标题和正文效果，以及 query-loop Block 渲染出的近期文章列表]

Hook / Function 速查

常见坑

• 忘记新建（哪怕是空的）theme.json 文件——可视化编辑器界面会完全打不开、显示空白（EP176 提醒）
• 模板文件里直接写裸 HTML，不用区块注释包裹——前台可能看起来没问题，但后台编辑器会报「无法预览」的错误，等于失去了 FSE 最大的可视化编辑能力
• 误以为用了 Block Theme/FSE 之后就再也不需要写 PHP——核心 Block（如 query-loop）能力有限，做不到自定义关联查询、meta 筛选这类复杂需求，这些场景依然需要自己写 PHP 驱动的自定义 Block
• 只在编辑器里改模板、从来不同步回 .html 源文件——一旦不小心点了「清除自定义项」，编辑器里的修改会全部丢失，回到源文件的旧版本

延伸 / 后续讲座会用到

下一讲继续讨论 2022 默认主题的设计思路，然后正式开始动手搭建这个 Block Theme 的其余部分。

Sources

Udemy：

• Become a WordPress Developer: Unlocking Power With Code — Section 28, EP176, EP177