块编辑器开发文档

Theme.json 版本 1 参考

💡 云策文档标注

概述

本文档是 theme.json 版本 1 的规范,适用于 WordPress 5.8 或更高版本。它详细列出了 theme.json 架构中定义的设置和样式属性,为开发者提供配置主题的参考。

关键要点

  • theme.json 版本 1 与 WordPress 5.8 及以上版本兼容,但版本 2 已在 WordPress 5.9 中发布,新功能仅添加到新版本中。
  • WordPress 将继续支持 theme.json 版本 1,但建议开发者参考迁移指南升级到最新版本。
  • 文档包含设置(如 border、color、layout、spacing、typography)和样式(如 border、color、spacing、typography)的属性列表,每个属性有类型、默认值和属性说明。
  • JSON 架构可通过特定 URL 获取,例如 https://schemas.wp.org/wp/5.8/theme.json,用于编辑器开发。

注意事项

  • 自定义 CSS 属性使用 --wp--custom--{key}--{nested-key}: {value}; 格式,键名从驼峰式转换为短横线分隔,避免使用 -- 在键名中。
  • 建议开发者查看 theme.json 使用指南以获取实际示例和指导。

📄 原文内容

This is the specification for version 1 of theme.json. This version works with WordPress 5.8 or later.

Theme.json version 2 has been released with WordPress 5.9. WordPress will continue to support theme.json version 1. However new features will only be added to [new versions](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/).

When you are ready to upgrade, see the [theme.json migration guide](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/#migrating-from-v1-to-v2) for details on updating to the latest version.

This reference guide lists the settings and style properties defined in the theme.json schema. See the theme.json how to guide for examples and guidance on how to use the theme.json file in your theme.

JSON Schema

The last schema for version 1 is available at `https://schemas.wp.org/wp/5.8/theme.json`.

Theme.json schemas for each WordPress version are available at https://schemas.wp.org/wp/{{version}}/theme.json`. For example a schema for WordPress 5.8 is available athttps://schemas.wp.org/wp/5.8/theme.json`.

See Developing with theme.json for how to use the JSON schema in your editor.

Settings

border

Settings related to borders.

Property Type Default Props
customRadius boolean false

color

Settings related to colors.

Property Type Default Props
custom boolean true
customDuotone boolean true
customGradient boolean true
duotone array colors, name, slug
gradients array gradient, name, slug
link boolean false
palette array color, name, slug

layout

Settings related to layout.

Property Type Default Props
contentSize string
wideSize string

spacing

Settings related to spacing.

Property Type Default Props
customMargin boolean false
customPadding boolean false
units array px,em,rem,vh,vw,%

typography

Settings related to typography.

Property Type Default Props
customFontSize boolean true
customLineHeight boolean false
dropCap boolean true
fontSizes array name, size, slug

custom

Generate custom CSS custom properties of the form --wp--custom--{key}--{nested-key}: {value};. camelCased keys are transformed to kebab-case as to follow the CSS property naming schema. Keys at different depth levels are separated by --, so keys should not include -- in the name.


Styles

border

Border styles.

Property Type Props
radius string

color

Color styles.

Property Type Props
background string
gradient string
text string

spacing

Spacing styles.

Property Type Props
margin object bottom, left, right, top
padding object bottom, left, right, top

typography

Typography styles.

Property Type Props
fontSize string
lineHeight string