WordPress theme.json 样式完全指南：从入门到精通

还在用 CSS 文件硬编码主题样式吗？WordPress 的 theme.json 提供了一种更现代化的方式——通过 JSON 数据结构直接控制主题的全局样式、元素样式和块样式。本文将带你彻底搞懂这套标准系统，从此告别繁琐的样式表维护。

---

为什么你应该关注 theme.json？

如果你开发过 WordPress 主题，肯定经历过这样的场景：为了改一个按钮颜色，翻遍整个 style.css 文件；为了让标题统一字体，需要记住数十个 CSS 类名；用户想微调样式，你却不得不教他们修改代码。

theme.json 的出现改变了这一切。它把样式定义从零散的 CSS 文件中解放出来，集中到一个结构清晰的 JSON 文件里。更棒的是，你在 theme.json 中定义的样式，会自动反映在“外观 > 编辑器 > 样式”界面中。这意味着用户可以在可视化界面下调整样式，而你作为开发者，也能直观地设计整个主题的视觉体系。

这套系统的核心逻辑很简单：越具体的样式，优先级越高。theme.json 支持三个层级：根（全局）、元素和块。每个层级都有明确的职责范围，接下来我们逐个击破。

---

根元素样式：定下全局基调

在 WordPress 里，“根元素”指的就是 HTML 的 <body> 标签。它是整个页面视觉输出的根基，根元素上定义的样式会像瀑布一样流向下游，除非被更具体的规则覆盖。

简单的例子

假设你要给整个网站设置默认文字颜色和背景色，只需要在 theme.json 的 styles 属性下直接定义：

json

{
    "version": 2,
    "styles": {
        "color": {
            "text": "#2c2c2c",
            "background": "#f7f3ee"
        }
    }
}

这段代码告诉 WordPress：给 <body> 加上深灰色的文字和米白色的背景。WordPress 会在编辑器和前端同时生成如下 CSS：

css

body {
    background: #f7f3ee;
    color: #2c2c2c;
}

由于 CSS 的层叠机制，这些颜色会成为全站的默认值。只有当你为某个更具体的元素（比如某个段落或按钮）单独指定颜色时，才会覆盖这里的设定。

根元素还支持什么？

除了颜色，根元素几乎支持所有样式属性：排版（字号、行高、字重）、间距（内边距、外边距）等。其中 styles.spacing.padding 有一个特殊用法——当它与 settings.useRootPaddingAwareAlignments 配合时，可以让块对齐功能感知到根元素的内边距，实现更精确的布局控制。

---

元素样式：让特定 HTML 标签统一风格

WordPress 定义了一套标准元素系统，通过 theme.json 的 styles.elements 节点来控制。这里的“元素”大多对应真实的 HTML 标签，但也有一些例外——比如 button 实际上会同时作用于 <button> 标签和具有按钮功能链接。

当前支持的元素清单

元素	说明	对应标签/场景
button	按钮样式	<button> 和 .wp-element-button 类
caption	媒体说明文字	<figcaption>
cite	引用来源	<cite>（引用块和拉取引用块中常用）
heading	所有标题	<h1> 到 <h6>
h1 ~ h6	单独控制各级标题	分别对应各层级标题
link	链接样式	<a> 标签

实操：统一按钮风格

假设你要让全站所有按钮白字红底，鼠标悬停时背景色变深一些。代码如下：

json

{
    "version": 2,
    "styles": {
        "elements": {
            "button": {
                "color": {
                    "text": "#ffffff",
                    "background": "#b5433a"
                },
                ":hover": {
                    "color": {
                        "background": "#8c332b"
                    }
                }
            }
        }
    }
}

WordPress 会生成类似这样的 CSS：

css

.wp-element-button,
.wp-block-button__link {
    background-color: #b5433a;
    color: #ffffff;
}

.wp-element-button:hover,
.wp-block-button__link:hover {
    background-color: #8c332b;
}

注意：WordPress 给大部分元素添加了 .wp-element-{元素名} 类名。button 元素的类名是 .wp-element-button，而 .wp-block-button__link 是为了保持对旧版 Button 块的兼容。

链接的伪类样式

link 和 button 元素支持标准的 CSS 伪类：:hover、:focus、:active 和 :visited。比如你想让链接在悬停时变个颜色：

json

{
    "version": 2,
    "styles": {
        "elements": {
            "link": {
                "color": {
                    "text": "#1a73e8"
                },
                ":hover": {
                    "color": {
                        "text": "#0d47a1"
                    }
                }
            }
        }
    }
}

一个容易被忽略的细节

heading 元素和独立的 h1~h6 元素是两套配置。如果你同时设置了 heading 和 h1，h1 的优先级更高。这意味着你可以用 heading 定义所有标题的通用样式，再用 h1 单独调整一级标题的特殊表现。

---

块样式：精准控制每个区块

块系统是 WordPress 的一大亮点，而 theme.json 让块的样式控制变得异常优雅。无论核心块还是三方插件块，只要在 styles.blocks 下指定块名称，就可以为该块添加样式。

块命名的规则

每个块都有一个“命名空间/块名”的标识。核心 WordPress 块的命名空间都是 core，比如 Image 块就是 core/image，Paragraph 块是 core/paragraph。三方插件的块名称可以在其 block.json 文件中找到。

给 Image 块加个圆角

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/image": {
                "border": {
                    "radius": "8px"
                }
            }
        }
    }
}

WordPress 会生成：

css

.wp-block-image img {
    border-radius: 8px;
}

注意这里生成的是针对 img 子元素的样式，而不是容器本身。不同的块，WordPress 会选择合适的 CSS 选择器来应用你的样式。

块内嵌套元素：更精细的控制

你不仅能给块本身加样式，还能针对块内部的特定元素进行定制。elements 属性就是干这个的。

假设你想让 Pullquote 块的引用文字变大，同时控制其内部的 <cite> 元素字体大小永远不小于 1.5rem 且不超过父级字号的 50%：

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/pullquote": {
                "typography": {
                    "fontSize": "2.25rem"
                },
                "elements": {
                    "cite": {
                        "typography": {
                            "fontSize": "max(50%, 1.5rem)"
                        }
                    }
                }
            }
        }
    }
}

生成的 CSS：

css

.wp-block-pullquote {
    font-size: 2.25rem;
}
.wp-block-pullquote cite {
    font-size: max(50%, 1.5rem);
}

这种写法让 cite 元素既能继承引用块的上下文，又能保持自己的尺寸逻辑。

---

块样式变体（Block Style Variations）

从 WordPress 6.2 开始，你可以在 theme.json 中直接修改核心块样式变体（也就是“块样式”）。这个功能让你无需写一行自定义 CSS，就能调整官方自带的风格选项。

修改 Button 块的 Outline 变体

假设你想让“轮廓”样式的按钮边框更粗，颜色跟随当前文字色：

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/button": {
                "variations": {
                    "outline": {
                        "border": {
                            "color": "currentColor",
                            "style": "solid",
                            "width": "2px"
                        }
                    }
                }
            }
        }
    }
}

核心块样式变体清单

块	可用变体
core/button	outline, fill
core/image	rounded
core/quote	plain
core/site-logo	rounded
core/separator	wide, dots
core/social-links	logos-only, pill-shape
core/table	stripes
core/tag-cloud	outline

注意：目前只支持官方核心块的变体，自定义块样式变体暂不支持在 theme.json 中调整，相关功能还在开发中。

---

三个层级的优先级规则

理解优先级是驾驭 theme.json 的关键。用一句话概括就是：块样式 > 元素样式 > 根样式。

比如你同时定义了：

• 根样式：color.text = "#333"
• 链接样式：color.text = "#1a73e8"
• 按钮块样式：color.text = "#ffffff"

那么 Paragraph 块中的链接会显示蓝色（元素样式覆盖根样式），而 Button 块中的文字会显示白色（块样式覆盖元素样式）。

这个规则让你可以从全局到局部逐层精细化控制，实现“粗细结合”的设计策略。

---

总结

theme.json 的样式系统把 WordPress 主题开发从混乱的 CSS 文件管理中解放出来，用一套清晰、可维护的 JSON 结构取代了零散的样式覆写。掌握根、元素、块这三个层级的协作方式，你就能构建出既统一又灵活的现代化主题。从今天开始，把 theme.json 当作你主题样式的主控台吧——你的用户和你自己，都会感谢这个选择。