WordPress theme.json 样式属性完全指南

发布于 作者:

在 WordPress 主题开发中，theme.json 文件承担着样式管理的核心职责。它提供了一种结构化的方式，让开发者能够统一定义全局样式、区块样式以及元素样式。这份指南将带您逐一拆解所有可用的样式属性——包括边框、颜色、尺寸、滤镜、阴影、间距和排版——用直观的方式说明它们如何工作，以及如何在您的主题中有效运用。无论您是刚开始接触 WordPress 开发，还是希望更深入地掌握站点编辑器的样式系统，这篇文章都会成为一份实用的参考资料。

一、边框（Border）

边框属性允许您为元素添加四条边的轮廓线，或者单独控制某一条边。

统一设置四个边：

json

{
    "version": 2,
    "styles": {
        "border": {
            "color": "#222222",
            "style": "solid",
            "width": "2px"
        }
    }
}

这里定义了所有边框为深灰色、实线、2像素宽。

单独控制每条边：

json

{
    "version": 2,
    "styles": {
        "border": {
            "top": {
                "color": "#cc0000",
                "style": "solid",
                "width": "3px"
            },
            "bottom": {
                "color": "#cccccc",
                "style": "dashed",
                "width": "1px"
            }
        }
    }
}

还可以单独使用 border.radius 来设置圆角：

json

{
    "version": 2,
    "styles": {
        "border": {
            "radius": "8px"
        }
    }
}

border-radius 也可以精细控制每个角，比如 "radius": { "topLeft": "8px", "bottomRight": "4px" }。

二、颜色（Color）

颜色属性决定文字、背景和链接的默认配色。

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/group": {
                "color": {
                    "text": "#1a1a1a",
                    "background": "#f5f5f5",
                    "link": "#0066cc"
                }
            }
        }
    }
}

这段代码给“组”区块设置了深灰色文字、浅灰背景，链接用了标准的蓝色。

color.link 比较特殊——它只作用于区块内部的 <a> 标签，不会影响普通文本。这在设计文章内容或导航区域时格外实用。

三、尺寸（Dimensions）

目前尺寸属性主要支持 minHeight，用来设定元素的小高度。

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/cover": {
                "dimensions": {
                    "minHeight": "60vh"
                }
            }
        }
    }
}

vh（视口高度单位）让封面区块的高度根据浏览器窗口大小变化。你也可以用 px、rem、% 等常见单位。

四、滤镜（Filter）

目前滤镜属性支持预设双色调（duotone）效果，通常用于图片。

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/image": {
                "filter": {
                    "duotone": "var(--wp--preset--duotone--blue-orange)"
                }
            }
        }
    }
}

var(--wp--preset--duotone--...) 这种写法调用了 WordPress 主题预设的双色调方案。你可以在 theme.json 的 settings 部分预先定义自己的双色调组合，然后在样式里引用。

五、阴影（Shadow）

阴影属性对应 CSS 的 box-shadow，让元素拥有立体感。

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/heading": {
                "shadow": "0 4px 8px 0 rgba(0, 0, 0, 0.12)"
            }
        }
    }
}

五个值分别对应：水平偏移、垂直偏移、模糊半径、扩散半径和颜色。不同的数值组合能营造出浮起、凹陷或发光等视觉效果。

六、间距（Spacing）

间距属性控制元素之间的空隙、外边距和内边距。

json

{
    "version": 2,
    "styles": {
        "spacing": {
            "blockGap": "2.5rem",
            "margin": {
                "top": "2rem",
                "bottom": "1.5rem"
            },
            "padding": {
                "left": "2rem",
                "right": "2rem"
            }
        }
    }
}

blockGap 控制多个区块之间的垂直间距（在 CSS 中对应 margin-top 和 gap 属性）。margin 和 padding 支持 top、right、bottom、left 四个方向。

注意 blockGap 与 margin、padding 的实际表现受区块布局影响，使用前建议在具体场景中测试效果。

七、排版（Typography）

排版属性涵盖了文字外观的大部分设置。

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/paragraph": {
                "typography": {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "fontSize": "1.125rem",
                    "fontStyle": "normal",
                    "fontWeight": "400",
                    "letterSpacing": "0.02em",
                    "lineHeight": "1.75",
                    "textDecoration": "none",
                    "textTransform": "none",
                    "writingMode": "horizontal-tb"
                }
            }
        }
    }
}

对于 fontFamily，建议使用系统字体堆栈，这样无需加载额外字体文件，页面加载速度更快。letterSpacing 的单位 em 是相对字号变化的，比 px 更灵活。

writingMode 常用于需要竖排文字的场景，例如中文古籍风格设计或某些亚洲语言排版。

八、自定义 CSS（css）

当内置属性无法满足需求时，可以使用 css 字段写入任意 CSS 代码。

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/gallery": {
                "css": "--wp--style--gallery-gap-default: 1.25rem;"
            }
        }
    }
}

这里的示例定义了一个自定义 CSS 变量。你还可以写完整的样式规则：

json

{
    "css": ".wp-block-gallery { --custom-gap: 1.5rem; } .wp-block-gallery .blocks-gallery-item { margin: 0; }"
}

css 字段是万能钥匙，但也容易让样式散落到各处。建议优先使用结构化属性，只有在确实无法实现时才借助自定义 CSS。

总结

theme.json 的样式系统将传统的 CSS 编写方式转化为结构化配置，让样式管理更加清晰。掌握这些属性后，您可以系统性地构建主题的视觉体系——从全局基调到每个区块的细节，都能在统一的框架内完成。

实际开发中，建议先在 settings 中定义设计变量（颜色调色板、字体大小梯度、间距单位），然后在 styles 中引用这些变量。这种“变量-引用”的模式让主题后期维护和调整变得轻松许多。

样式配置需要在实际页面中反复预览验证，不同区块对同一属性的响应方式可能略有差异，灵活调整才能达到理想效果。