EP185-186. “theme.json 配置内容宽度、调色板与 Block 默认样式”

新建 theme.json 文件，学习它能控制 Block Theme 的哪些整体设置。核心内容：① 光是新建一个空的 theme.json 就会让编辑器的内容宽度从「居中定宽」变成「占满全宽」——因为 WordPress 一旦发现主题提供了这个文件，就不再套用内建的默认值,而是完全交给主题自己决定；② 用 settings.layout.contentSize 精确控制博文/页面编辑器的内容宽度（区别于全站编辑器本身可以保留全宽);③ 单个 Block 也能通过 supports.align + 对应 attributes.align 默认值,让它即使身处窄内容区域也能占满全宽（Banner 区块就是这么做的）;④ 用 settings.color.palette 定义一套主题配色,自动出现在所有 Block 的颜色选择器里；⑤ 用 styles.blocks 给指定核心 Block（比如 core/button）设置默认样式,还能引用调色板里定义的颜色变量;⑥ 用 settings.blocks/顶层 settings 分别关闭「某个 Block 专属」或「全局」的某些设置项（比如按钮的边框选项、全局字号选项）。最后强调：theme.json 里的属性名和取值没有什么「原理」好讲,纯粹靠查官方文档,不需要死记硬背。

涉及文件

• wp-content/themes/fictional-university-block-theme/theme.json （新建）
• wp-content/themes/fictional-university-block-theme/our-blocks/banner.js （修改，新增 supports.align）

代码实现

theme.json（完整文件）：

{
  "version": 2,
  "styles": {
    "blocks": {
      "core/button": {
        "color": {
          "text": "#FFFFFF",
          "background": "var(--wp--preset--color--pizza)"
        }
      }
    }
  },
  "settings": {
    "typography": {
      "fontSizes": []
    },
    "blocks": {
      "core/button": {
        "border": {
          "color": false,
          "radius": false,
          "style": false,
          "width": false
        }
      }
    },
    "color": {
      "palette": [
        {
          "slug": "pizza",
          "color": "#0d3b66",
          "name": "Primary"
        },
        {
          "slug": "secondary",
          "color": "#ee964b",
          "name": "Secondary"
        },
        {
          "slug": "background",
          "color": "#FFFFFF",
          "name": "Background"
        },
        {
          "slug": "foreground",
          "color": "#333333",
          "name": "Foreground"
        }
      ]
    },
    "layout": {
      "contentSize": "840px"
    }
  }
}

our-blocks/banner.js：让 Banner Block 即使在窄内容区域也能撑满全宽：

registerBlockType("ourblocktheme/banner", {
  title: "Banner",
  supports: {
    align: ["full"]
  },
  attributes: {
    align: { type: "string", default: "full" }
  },
  edit: EditComponent,
  save: SaveComponent
})

关键改动点：

• 一新建（哪怕完全空的）theme.json，编辑器内容宽度行为就会变：没有这个文件时，WordPress 用内建的默认值（作者提到大约是 840px 左右）让博文编辑器和全站编辑器的内容都居中定宽；只要主题提供了这个文件（哪怕是空的 {}），WordPress 就会认为「主题自己会决定这些值」，两个编辑器的内容都会变成占满全宽——这一步纯粹是观察这个文件「存在与否」本身就会改变行为，不需要写任何内容就能验证
• version 属性：写这门课时是 2，官方后续肯定会继续升版本——因为 Block 编辑器和 FSE 相关能力变化非常快，需要一套版本机制避免不同版本行为混乱、互相冲突
• settings.layout.contentSize：控制博文/页面编辑器里内容区域的宽度（这里设成 "840px"，跟 WordPress 默认值一致，作者提到自己实际测试后决定采用官方默认值而不是最初设想的 800px）——这个设置只影响博文/页面编辑器，不影响全站编辑器（模板本身）的宽度，这是作者刻意的取舍：写文章时希望行宽适中方便阅读,但拼装 Banner/页头这类整站级别的模板内容时希望能真正预览到「占满全宽是什么效果」
• 单个 Block 通过 supports.align 突破默认的居中定宽限制：supports: {align: ["full"]} 声明这个 Block 支持「对齐」这个特性、且只允许 full（占满全宽）这一个选项；同时在 attributes 里加一个 align: {type: "string", default: "full"}，让它默认就是全宽状态，不需要用户手动去点选——这样即使在博文编辑器这种被 contentSize 限制成窄内容区域的地方插入 Banner，它依然会撑满整个可用宽度
• settings.color.palette——定义主题配色：一个数组，每个颜色对象包含 slug（给代码/CSS 变量用的英文标识符，可以随便取名）、color（十六进制色值）、name（人类可读的显示名称，会出现在颜色选择器的提示文字里）——定义好之后，所有支持改颜色的核心 Block（比如段落的文字颜色）,右侧设置面板里都会自动出现这几个主题配色可选
• slug 名字可以随便取，跟颜色实际含义没有强制关联：这一讲刻意做了个演示——把本来叫 primary（对应 Fictional University 的主蓝色）的 slug 改名叫 pizza，功能完全不受影响，只是用来证明「这个字段就是个自由命名的标识符」；这个改动被保留在了最终文件里，palette 第一项的 slug 确实是 pizza（name 依然显示为人类可读的 "Primary"）
• styles.blocks.{Block名}——给指定核心 Block 设置默认样式：这里给 core/button 设置了默认的文字颜色（#FFFFFF，白色）和背景色——背景色没有直接写死一个十六进制值，而是用 var(--wp--preset--color--pizza) 引用调色板里 slug 为 pizza 的颜色，命名规则固定是 --wp--preset--color--{slug}
• 调色板颜色会被 WordPress 自动转换成 CSS 自定义属性（变量），在前台和编辑器双端都能用——右键检查按钮元素的 CSS，能看到实际用的就是这个 CSS 变量，WordPress 负责生成对应的 :root 变量定义，开发者不需要自己手写这层转换
• 主题设置的默认值可以被网站所有者在编辑器里覆盖，但不会改回源文件：在全站编辑器的「样式 → 颜色 → 调色板」里，非技术的网站所有者可以自己把 pizza 这个颜色改成任意别的颜色（比如荧光绿）,效果立刻应用到前台；这个自定义值实际存进了数据库（可以在 wp_posts 表里找到对应记录，看到里面存的就是覆盖后的调色板设置），theme.json 源文件本身完全没变——如果想恢复,在编辑器的「样式」菜单点「重置为默认值」即可,跟模板文件的「清除自定义项」是同一套「文件是安全的原始版本、数据库存的是运行时自定义层」的思路
• settings.blocks.{Block名}.{设置分类}——关闭某个 Block 专属的设置项：这里给 core/button 的 border 底下四个属性（color/radius/style/width）全部设成 false，效果是编辑器右侧面板里彻底不再出现「边框」这个设置分类，用户没法给按钮设置边框
• 顶层 settings.typography.fontSizes 设成空数组 []——全局关闭字号选项：跟上面那种「针对某个 Block」的写法不同，这个设置写在 settings 顶层（不在 blocks 底下），效果是对所有 Block 都生效——点击按钮或任意支持字号设置的 Block,右侧面板都不再出现修改字号的选项
• 这份配置文件的属性名/取值没有「原理」可讲，纯靠查官方文档：作者明确说这不是需要提前系统学习记忆的知识,而是「想实现什么效果就去 developer.wordpress.org 查对应属性该怎么写」的工具书性质内容——因为 FSE 相关功能变化很快，官方文档当时也分散在好几个页面，没有一份统一权威的参考
• 这一讲埋下一个伏笔，留给下一讲：接下来要做的「按钮 Block」允许用户选择按钮颜色时，作者不打算用 theme.json 的调色板机制,而是要在自定义 Block 代码里自己写死颜色选项——原因是写这门课时（2022 年初）还没有找到简单的办法能让 theme.json 里设置的东西完全禁止网站所有者覆盖,如果某些颜色选项无论如何都不应该被终端用户随意修改，就只能自己在 Block 代码里手写而不是依赖 theme.json

Hook / Function 速查

常见坑

• 以为不新建 theme.json 就是「用了默认设置、不会有任何变化」——实际上光是文件存在与否，就会影响编辑器内容宽度这类全局行为，容易在排查样式问题时忽略这一点
• 想让某个 Block 突破 contentSize 限制、占满全宽，只写了 supports.align，忘记在 attributes 里同步设置 align 的默认值——用户每次插入都要手动选择对齐方式，而不是自动就是全宽
• 以为 theme.json 里设置的调色板/样式是不可更改的死值——网站所有者依然可以在全站编辑器的「样式」菜单里覆盖这些默认值，只是覆盖结果存在数据库而不会改动源文件
• 需要「终端用户绝对不能修改」的颜色/样式选项，还是用 theme.json 的调色板机制来实现——录课当时没有可靠的办法完全锁死这些设置不被覆盖，这种场景应该改为在 Block 代码里自己写死选项（下一讲的按钮 Block 就是这么处理的）

[截图：核心 Button Block 右侧设置面板的颜色选择器，出现调色板里定义的 Primary/Secondary 等自定义颜色选项]

延伸 / 后续讲座会用到

下一讲开始做自定义按钮 Block（generic-button），颜色选项会选择自己在代码里写死,而不是依赖 theme.json 的调色板。

Sources

Udemy：

• Become a WordPress Developer: Unlocking Power With Code — Section 28, EP185, EP186