Theme.json - 主题开发手册

theme.json是什么

Theme.json是一个用于主题样式和区块设置的配置文件。

该功能是在WordPress 5.8版本中添加的，在旧版本的WordPress中不工作，除非你激活了Gutenberg 插件。

你可以用theme.json做的一些事情：

启用或禁用各种功能，如：drop cap、padding、margin和自定义行高
添加多个调色板、渐变和双色调
添加字体大小
为内容和宽幅内容添加默认宽度
添加自定义CSS属性
将模板片段分配到模板片段区域

当你在主题中添加theme.json，模板编辑器就被启用了。

在WordPress 5.8（版本1）、WordPress 5.9（版本2）和Gutenberg插件（实验性功能）中，theme.json可用的内容有重要区别。
本页包含theme.json的第2版信息。

本页是对区块编辑手册中How-to 指南和theme.json 参考的补充。

如何创建theme.json文件

在主题根目录创建theme.json文件。

接下来，添加一对大括号，在大括号内，包含版本号。

{
    "version": 2
}

包含版本属性是很重要的，否则，数据将被解析为 "version 0"，这与这里概述的预期行为有很大不同。

有两个主要部分：

Settings：在这里你可以定义你的区块控件和调色板、字体大小等等。
Styles：在这里，你将这些颜色和字体大小应用于网站和区块。

添加名称，将你的settings放在大括号之间，并以逗号分隔对象。

{
    "version": 2,
    "settings": {
          "color": {},
          "typography": {}  
    }
}

你可以用settings和styles来设置网站和区块：

将全局性的、全站性的settings放在根层次上
将区块设置放在"blocks"内，后面是区块名称。

{
    "version": 2,
    "settings": {
        "color": { ... }, // Global settings
        "blocks": {
            "core/group": { 
                "color": { ... }, // Group block color settings
                "typography": { ... } // Group typography settings
            }
        }
    }
}

预设值

WordPress使用来自theme.json的数据来控制编辑器的区块设置和创建CSS的自定义属性。这方面的一个例子是调色板。这些值被用来为用户提供调色板选项，并生成CSS属性，你可以在theme.json的其他地方或主题的CSS中使用。

这个例子显示了一个带有单一黑色的调色板：

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "name": "Black",
                    "slug": "black",
                    "color": "#000000"
                }
            ]
        }
    }
}

这将导致在网站body中生成CSS变量：

--wp--preset--color--black: #000000;

这个例子显示了只在段落块中添加了一个单一的蓝色的调色板：

{
    "version": 2,
    "settings": {
            "blocks": {
                "core/paragraph": {
                    "color": {
                        "palette": [
                            {
                                "name": "Blue",
                                "slug": "blue",
                                "color": "#0000FF"
                            }
                        ]
                    }
                }
            }
        }
    }        
}

该例子将在段落块元素中提供以下CSS变量：

--wp--preset--color--blue: #0000FF;

自定义值

存储在settings.custom区域（或settings.block.BLOCKNAME.custom区域）的值会生成CSS属性，你可以在theme.json文件或主题CSS的其他地方使用。

{
    "version": 2,
    "settings": {
            "custom": {
                "fruit": "apple"
            },
            "blocks": {
                "core/paragraph": {
                    "custom": {
                        "fruit": "pear"
                    }
                }
            }
        }
    }        
}

上述做法将导致CSS变量--wp--custom--fruit被创建，其值为"apple"。但对于"core/paragraph"元素，其值将是"pear"。

theme.json可以被添加到任何主题中

Theme.json既可用于基于PHP的经典主题，也可用于块状主题。Theme.json不能与经典编辑器一起工作。

如果你在一个现有的主题上添加theme.json文件，你可能需要调整主题的CSS，删除重复的样式，以便theme.json能够正常工作。
此外，"full"和"wide"块的对齐机制在有theme.json存在的情况下工作方式不同，应予以考虑。

请注意，theme.json中的设置取代了对add_theme_support()的许多调用。theme.json中的调色板相当于add_theme_support( 'editor-color-palette', …).的作用。
当两者都存在时，来自theme.json的调色板具有优先权。

Settings（设置）

Color（颜色）

每种颜色、渐变色和双色调都有三个键值对：

slug：在CSS预设中使用
[color, gradient, 或 colors]
name：编辑器中的可见名称（可选）

Color palette（调色板）

调色板项目的颜色值可以是任何有效的CSS颜色值，如 "blue"或十六进制颜色，如 "#00FF00"。

Gradients（渐变）

你可以用任何有效的CSS颜色值来创建渐变，并把它们分配给 "gradient"键。下面的例子使用了从调色板上生成的CSS属性。

Duotone（双色调）

双色调的颜色在一个分配给"colors"键的数组中表示。它们必须是十六进制或RGB颜色值。

{
    "version": 2,
        "settings": {
            "color": {
                "palette": [
                    {
                        "slug": "purple",
                        "color": "#D1D1E4",
                        "name": "Purple"
                    },
                    {
                        "slug": "yellow",
                        "color": "#EEEADD",
                        "name": "Yellow"
                    }
                ],
                "gradients": [
                    {
                        "slug": "purple-to-yellow",
                        "gradient": "linear-gradient(160deg, var(--wp--preset--color--purple), var(--wp--preset--color--yellow))",
                        "name": "Purple to Yellow"
                    }
                ],
                "duotone": [
                    {
                        "slug": "purple-and-yellow",                    
                        "colors": [ "#D1D1E4", "#EEEADD" ],
                        "name": "Purple and yellow"
                    }
                ]
            }
        }
    }
}

Typography（排版）

Font size（字体大小）

在theme.json中定义的字体大小取代了通过主题支持分配的‘editor-font-sizes’值。它们由相同的三个值组成：slug、size和name。

{
    "version": 2,
    "settings": {
        "typography": {
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "1rem",
                    "name": "Small"
                },
                {
                    "slug": "medium",
                    "size": "1.5rem",
                    "name": "medium"
                }
            ]
        }
    }
}

Layout（布局）

布局设置启用wide和full-width区块。请注意，这里利用的对齐机制与之前通过align-wide主题支持启用的不同。

{
    "version": 2,
    "settings": {
        "layout": {
            "contentSize": "840px",
            "wideSize": "1100px"
        }
    }
}

Spacing（间距）

启用自定义margin、padding和自定义间距单位：

{
    "version": 2,
    "settings": {
        "spacing": {
            "padding": true,
            "margin": true,
            "units": [ "px", "em", "rem", "vh", "vw", "%" ]
        }
    }
}

启用和禁用settings

在settings中，你可以在编辑器中启用或禁用区块。

以下功能是默认启用的：

自定义颜色(颜色选择器)
自定义双色调(颜色选择器)
自定义渐变(颜色选择器)
自定义字体大小
首字下沉

要禁用它们，你需要将该设置的值设为false。

这个例子禁用了调色板和渐变的自定义颜色：

{
    "version": 2,
    "settings": {
        "color": {
            "custom": false,
                        "customGradient": false
                 }
         }
}

这个例子禁用了首字下沉：

{
    "version": 2,
    "settings": {
        "typography": {
            "dropCap": false
                 }
         }
}

以下功能在默认情况下是禁用的：

链接颜色
Padding和margin
自定义行高

要启用它们，你需要将该设置的值设为true。

示例

{
    "version": 2,
    "settings": {
        "color": {
            "link": true
                 },
                "typography": { 
                         "lineHeight": true
                }
         }
}

或者，你可以启用AppearanceTools，在一个单独的设置中启用这些功能。

border: color, radius, style, width
color: link
spacing: blockGap, margin, padding
typography: lineHeight

{
    "version": 2,
    "settings": {
        "appearanceTools": true,
         }
}

Styles（样式）

和settings一样，应用于网站body的样式被放置在styles部分的根层。

{
    "version": 2,
    "settings": { ... },
    "styles":{
        "color":{
            "background":"var(--wp--preset--color--white)",
            "text":"var(--wp--preset--color--black)"
        },
        "typography":{
            "fontSize":"1.5rem",
            "fontFamily":"var(--wp--preset--font-family--system-fonts)",
            "lineHeight":"1.5"
        },
        "spacing":{
            "margin":{
                "top":"0px",
                "right":"0px",
                "bottom":"0px",
                "left":"0px"
            }
        }
    }
}

应用于区块的styles被放在style.block.BLOCKNAME下：

{
    "version": 2,
    "settings": { ... },
    "styles": {
        "blocks": {
            "core/post-title": {
                "typography": {
                    "fontSize":"var(--wp--preset--font-size--extra-large)"
                }
            },
            "core/paragraph": {
                "typography": {
                    "fontSize":"var(--wp--preset--font-size--normal)"
                }
            }
        }
    }
}

Theme.json 元素

区块可以有多个HTML元素。你可以使用elements为块内的标题（H1-H6）和链接设置样式
在这个例子中，背景色和padding被添加到文章摘录块内的"更多"链接：

{
    "version": 2,
    "settings": { ... },
    "styles": {
        "blocks": {
            "core/post-excerpt": {
                "elements": {
                    "link": {
                        "color": {
                            "background": "var(--wp--preset--color--light-grey)"
                        },
                        "spacing": {
                            "padding": {
                            "top": "calc(.667em + 2px)",
                            "right": "calc(1.333em + 2px)",
                            "bottom": "calc(.667em + 2px)",
                            "left": "calc(1.333em + 2px)"
                        }
                    }
                }
            }
        }
    }
}

分配模板片段

在templateParts部分为模板区域指定默认的模板片段。
添加三个键：name：模板片段文件的文件名，不含文件扩展名；area：模板区域的名称；title：编辑器中的可见名称。有三个模板区域可供选择：header（页眉）、footer（页脚）和uncategorized（常规）。

来自Twenty Twenty-Two的例子：

"templateParts": [
    {
        "name": "header",
        "title": "Header",
        "area": "header"
    },
    {
        "name": "header-large-dark",
        "title": "Header (Dark, large)",
        "area": "header"
    },
    {
        "name": "header-small-dark",
        "title": "Header (Dark, small)",
        "area": "header"
    },
    {
        "name": "footer",
        "title": "Footer",
        "area": "footer"
    }
]

定义自定义模板

在经典主题中，自定义页面模板是用文件头来标识的。在块状主题中，你可以在theme.json文件中列出区块模板。
所有列在theme.json的customTemplates的模板都可以在网站编辑器中选择。要使模板在模板编辑器中可编辑，模板的文件名需要以文章类型为前缀（通常是post-或page-）。

添加两个键：name：模板片段文件的文件名，没有文件扩展名；title：在编辑器中可见的名称。还有一个可选的设置，你可以决定哪些文章类型可以使用该模板。键名是postTypes，后面是文章类型的名称。

"customTemplates": [
    {
        "name": "page-home",
        "title": "Page without title"
    },
    {
        "name": "page-contact",
        "title": "Contact",
        "postTypes": [ "page" ]
    }
]

切换全局样式

一个主题可以有多个额外的JSON文件，在顶层设置中提供不同的样式。这些样式选项将出现在侧边编辑器的浏览样式下。当用户选择切换样式时，它将覆盖默认theme.json上的样式。有几个要求需要牢记。

最低要求的WordPress版本是6.0
默认的theme.json必须位于根目录下，并且需要使用theme.json version 2来声明
额外的JSON文件必须被放置在/styles目录

在额外的JSON文件中添加title来标识这个可切换的样式名。用户将在网站编辑器上看到该标题。如果一个JSON文件中缺少title，将使用文件名来标识。

通过下面的例子，用户在侧边编辑器中将看到一个"Dark"样式，可供切换。当用户选择"Dark"样式时，背景和文本颜色属性将覆盖默认样式。

{
    "version": 2,
    "title": "Dark",
    "styles": {
        "color": {
            "background": "black",
            "text": "white"
        }
    }
}

资源链接

更新日志：

Updated 2022-05-17 添加切换全局样式
Updated 2022-02-15. 为间距添加了 % 单位，添加了关于templateParts和customTemplates的信息。
Created 2022-01-20

Written by @pbking and @poena.