在theme.json中使用属性和键值对

了解 theme.json 文件的结构和属性是区块主题开发的基础。该文件是所有基于区块的主题的主要配置中心。

无论你是从头开始创建一个主题，还是对现有主题进行自定义、开发风格变体或制作子主题，掌握theme.json的使用方法都是至关重要的。

幸运的是，JSON（JavaScript Object Notation，JavaScript 对象符号）是一种人类可读的格式，其分层结构可将信息从一般属性组织到特定属性。就 theme.json 而言，熟悉层叠样式表（CSS）比深入了解 JavaScript 更有意义。

本文旨在分解 theme.json 文件中的主要和次要（嵌套）属性，重点关注键设置和样式属性。这些是文件的核心元素，我们将为每个元素提供详细解释和代码示例。

我们将在上一篇文章《释放主题 .json 的力量》：像专业人士那样定制 WordPress 主题中奠定的基础上继续努力，尤其是在使用 theme.json 文件属性部分。

区块主题中如何呈现样式

WordPress 使用内置的层叠过程来呈现网站的样式。当多个来源定义了相同的设置或样式时，WordPress 必须确定哪一个优先。以下是 WordPress 决定应用哪种样式所遵循的优先顺序：

1. WordPress 核心–  theme.json 文件位于 WordPress 的 wp-includes 目录下。这个文件会在主要的 WordPress 版本更新时被更新，不应该直接编辑。
2. 主题– 主题开发人员使用的主要 theme.json 文件，用于定义主题的设置、样式和其他属性。
3. 风格变体– 如果主题包含风格变体，每个变体都有自己的 theme.json 文件，存储在主题的 styles 子目录中。
4. 子主题– 与经典主题一样，子主题可以修改父主题，而无需更改其文件（可选）。
5. 子主题样式变化– 与常规样式变化类似，子主题可以在其样式子目录中拥有自己的 theme.json 文件（可选）。
6. 用户创建的样式– 这些是通过 WordPress 编辑器添加并存储在数据库中的自定义样式（用于页面、文章或整个网站）。

级联顺序确保来自优先级较高来源的样式优先于来自优先级较低来源的样式。例如，主题的 theme.json 文件中的设置将覆盖 WordPress 核心的 theme.json 文件。同样，子主题的样式变化将优先于父主题的样式变化。

用户创建的样式（6）具有最高优先级，在级联中优先于所有其他样式。

本文的重点是位于任何 WordPress 区块主题根目录下的 theme.json 文件。

主要属性及其键值参考

让我们来探讨一下 theme.json 中的七个顶级对象，为了便于理解，我们将它们分成了三个部分。

深入了解前的几个定义

在使用theme.json 时，你可能会发现重要组件的定义各不相同。为清晰起见，我们在本文中将对它们进行如下定义：

1. 章节 – 在 theme.json 文件中用于组织和分组顶层选项的部分。从某种意义上来说，它们可以被视为顶层对象（top-level objects），它们帮助将不同的配置选项分类，以便更容易地理解和管理。
2. 对象 –theme.json文件中的主要元素，如 settings 和 styles。
3. 属性 – 对象中的组件。例如，settings 对象包含 12 个不同的属性。
4. 键值对 – 属性由键值对组成。键代表一个属性，用引号括起来。值可以是布尔值、字符串或数组。

当我们提到“默认情况下”时，我们指的是 theme.json 文件中的默认配置，该文件位于wp-includes/theme.json 中。

最后，“用户”是指任何使用 WordPress 管理后台的人，他们可以修改网站、页面或文章编辑器中的设置。

语法概述

1. 布尔值不用引号括起来。
2. 字符串用双引号括起来。
3. 数组用方括号 [] 括起来。
4. 对象用大括号 {} 括起来，包含多个属性或嵌套对象。
5. 逗号用于分隔对象中的多个键值对。

下面是一个典型的语法示例：

{
"house": {
"rooms": "kitchen"
}
}

属性分组

为了便于浏览，我们将属性分为三个部分：

1. 基本属性
2. 设置和样式属性
3. 模板和样板属性

为了简化示例，我们有时会省略外部对象包装器。而不是显示整个结构：

{
"settings": {
"appearanceTools": false,
"background": {
"backgroundImage": true
}
}
}

We might shorten it to:

"appearanceTools": false,
"background": {
"backgroundImage": true
}

提示：部分示例用于说明概念，可能并不代表主题开发中的实际应用。

基本属性

在 theme.json 文件的开头，你通常会发现两个关键属性：$schema 和 version。这些属性通常位于文件的顶部。当前的模式版本是 3，在 WordPress 6.6 中引入。

"$schema": "https://schemas.wp.org/wp/6.6/theme.json", "version": 3

设置和样式属性

如果你熟悉经典主题，就会把设置属性看作通常在 functions.php 文件中设置并在 WordPress 管理后台的“外观”>“自定义”版块中显示的特性和功能。

而样式则类似于以前存在于 styles.css 文件中的 CSS 属性，用于控制主题的布局和设计。

设置

除 block 和 elements 属性外，所有其他设置都是全局设置。由于这些设置中有很多都是布尔值，因此它们就像是启用或禁用用户界面功能的切换开关。

值得注意的是，并不是所有的键都适用于任何情况。例如，不可能允许用户设置段落块的最小高度。

外观工具

这些设置可以通过使用 "appearanceTools": true 来集体或单独启用。

启用此功能后，WordPress 编辑器中的各种用户界面选项就会显示出来，从而节省开发人员的时间。默认情况下，这些工具是禁用的（"appearanceTools":false）。

appearanceTools 中的键包括：

• background
  • backgroundImage — 允许用户为图块添加背景图片。
  • backgroundSize — 定义背景图片的缩放方式（覆盖、包含等）。
• border
  • color — 启用颜色选择（用于设置边框颜色）。
  • style — 让用户选择边框样式（实线、虚线、点线等）。
  • width — 控制边框的厚度。
  • radius — 允许用户通过调整边框半径来设置圆角。
• color
  • link — 为内容中的链接设置颜色。
  • heading — 允许用户为标题标记（ <h1>、<h2> 等）定义颜色。
  • button — 控制主题中按钮的颜色。
  • caption — 允许为标题设置自定义颜色。
• dimensions
  • aspectRatio — 允许用户控制区块的宽高比。
  • minHeight — 允许设置区块的最小高度。
• position
  • sticky — 允许用户将区块设置为固定，即在滚动时保持固定位置。
• spacing
  • blockGap — 控制区块之间的间距。
  • margin — 允许用户调整区块周围的边距。
  • padding — 控制区块内的填充，定义其内容和边框之间的空间。
• typography
  • lineHeight — 允许用户调整行高（文本行间距），以提高可读性。

举例说明：如果希望用户添加背景图片，同时禁用其他外观工具，请使用

"appearanceTools": false,
"background": {
"backgroundImage": true
}

由此产生的用户界面允许用户为组区块添加背景图片。

区块

blocks 属性允许用户启用每个区块的设置，这些设置可以覆盖全局设置。

例如：如果 appearanceTools 设置为 false，但仍想为区块显示边框控件，请使用：

"border": {
"color": true,
"style": true,
"width": true,
"radius": true
}

显示生成的用户界面，可以添加边框。

颜色

用户可通过该属性设置背景色、文本色或渐变色等颜色选项。

颜色属性中的键

• background– 控制区块或元素的背景颜色。
• custom– 启用或禁用用户选择自定义颜色的功能。
• customDuotone– 允许用户对图片应用自定义双色滤镜。
• customGradient– 启用自定义渐变选项。
• defaultDuotone– 提供默认的双色调图像滤镜选项。
• defaultGradient– 定义用户可用的默认渐变选项。
• defaultPalette– 控制主题的默认调色板。
• duotone– 允许在图像上使用双色调滤镜。
• gradient– 启用背景或其他元素的渐变选项。
• link– 设置主题中链接的颜色。
• text– 控制 text 颜色选项。
• heading– 设置标题（如 h1、h2 等）的颜色。
• button – 控制按钮颜色选项。
• caption– 为媒体元素设置标题颜色。

让我们举例说明：

示例 1：如果要禁用用户的颜色选择器，可以使用下面的方法：

"color": {
"custom": false
}

禁用颜色选择器用户界面。

示例 2：要设置自定义的主主题色和次主题色，可以使用此配置：

"color": {
"palette": [
{ "slug": "primary", "color": "#0000ff", "name": "Primary" },
{ "slug": "secondary", "color": "#ff0000", "name": "Secondary" }
]
}

由此产生的用户界面设置主色调和次主题色调。

尺寸

该属性提供了控制块尺寸（如宽度、高度和宽高比）的选项。

dimensions 属性中的键

• aspectRatio– 允许用户设置或锁定区块的纵横比（如 16:9、4:3）。
• defaultAspectRatios– 为区块定义默认宽高比。
• minHeight– 启用为区块设置最小高度的功能。

例如，要允许用户为支持的区块设置最小高度，请使用以下命令：

"dimensions": {
"minHeight": true
}

用户界面中设置的最小高度。

布局

layout 属性允许用户设置与布局相关的选项，如内容宽度和用户是否可以自定义布局。用户可以通过这些键来设置布局选项：

• contentSize– 设置区块的默认宽度。
• wideSize– 定义选择宽对齐选项时区块的宽度。
• allowEditing– 确定用户是否可以编辑布局选项。
• allowCustomContentAndWideSize– 启用 contentSize 和 wideSize 的自定义选项。

示例 ： 配置具有默认和宽对齐区块宽度的布局设置：

"layout": {
"contentSize": "620px",
"wideSize": "1000px"
}

设置和预览区块尺寸。

注：这些值是用户可以更改的起点。

灯箱

通过 lightbox 属性，用户可以启用图片的“点击即展开”功能，在点击时以更大的视图打开图片。

lightbox 属性中的键：

• enabled — 启用或禁用灯箱功能。
• allowEditing — 允许用户切换灯箱设置。

示例：要允许用户切换图片的灯箱功能，请使用此配置：

"blocks": {
"core/image": {
"lightbox": {
"allowEditing": true
}
}
}

切换灯箱效果。

位置

position 属性允许用户控制区块的位置，例如使区块在页面上固定位置。

示例：让区块可固定位置：

"position": {
"sticky": true
}

阴影

此属性可让用户通过使用预定义预置或自定义阴影为图块应用阴影效果。

shadow 属性中的键：

• defaultPresets —启用或禁用默认阴影预设。
• presets —允许用户定义自定义阴影预设。

下面是一个关闭默认阴影并定义名为“Natural”的自定义阴影的示例：

"shadow": {
"defaultPresets": false,
"presets": [
{ "name": "Natural", "slug": "natural", "shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)" }
]
}

在用户界面中设置阴影选项。

数字表示网站编辑器中的点击步骤，以演示用户界面。最后一步显示的是“Natural”阴影。

间距

该属性定义了编辑器中如何控制间距（padding、margin、gap）。

spacing 属性中的键：

• blockGap — 控制区块之间的间隙。
• margin — 允许用户设置区块周围的边距。
• padding — 提供在区块内设置填充的选项。
• units — 定义可用的间距单位（如 px、rem）。
• customSpacingSize — 允许用户设置自定义间距大小。
• spacingSizes — 定义一系列预设的间距大小。
• spacingScale — 允许缩放间距单位。

举例说明：要将用户的填充、边距、宽度和高度限制为两种测量单位（像素和 rem），并在网站编辑器中显示间距控件，请将 appearanceTools 设置为 true 并进行如下配置：

"spacing": {
"units": ["px", "rem"]
}

限制使用 2 个计量单位。

排版

该属性控制主题的文字相关设置，如字体大小、粗细和行高。

typography 属性中的键：

• defaultFontSizes — 定义用户可用的默认字体大小。
• customFontSize — 启用或禁用设置自定义字体大小的功能。
• fontStyle — 控制字体的样式（如普通、斜体）。
• fontWeight — 允许用户设置字体的重量（如粗体、浅色）。
• fluid — 启用流体排版，根据屏幕大小动态调整字体大小。
• letterSpacing —控制字母之间的间距。
• lineHeight — 设置每行文字的高度。
• textAlign — 允许控制文本对齐方式（如左对齐、居中对齐、右对齐）。
• textDecoration — 提供文本装饰选项（如下划线）。
• writingMode — 设置文本的书写模式（如水平或垂直）。

示例：要禁用自定义字体大小和 ropCap 选项，请使用以下命令：

"typography": {
"customFontSize": false,
"dropCap": false
}

删除自定义字体大小选项和 DropCap。

在这种情况下，这两个高亮显示的键都不会出现在编辑器中。

根元素内边距感知对齐

当一项名为“root padding aware alignments”的属性被设置为“true”时，它会确保宽度或全宽度的块级元素（例如，某些容器或背景图像）在页面根元素（如  <html> 或  <body>）上应用的内边距（padding）影响下，进行正确的对齐。

示例：

"useRootPaddingAwareAlignments": true

注：默认情况下，该属性设置为 false，因此会产生平齐设计。

当设置为 true 时，还必须将根的顶部、右侧、底部和左侧填充值定义为样式。(下文将详细介绍样式属性）。

"spacing": {
"padding": {
"top": "0",
"right": "100px",
"bottom": "0",
"left": "100px"
}
}

useRotPaddingAwareAignements 默认设置。

将 useRootPaddingAwareAlignements 设置与左右填充一起应用于正文（如上述代码所示），结果如下。

当 useRootPaddingAwareAlignments 设置为 true 时，应用左右填充。

样式

通过 styles 属性，你可以将 CSS 样式应用到根目录（默认）、特定元素或主题中的单个区块。

背景样式

你可以控制与背景相关的属性，如图像、定位和附件。

背景的常用键：

• backgroundImage — 定义区块或元素的背景图片。
• backgroundPosition — 设置背景图像的位置（如居中、右上角）。
• backgroundRepeat — 指定背景图像是否重复（例如，重复、不重复）。
• backgroundSize — 控制背景图片的大小（如封面、包含）。
• backgroundAttachment — 指定背景图片是固定还是随页面滚动。

例如，您可以为主题设置背景图片：

"background": {
"backgroundImage": {
"url": "https://joyofwp.com/wp-content/uploads/2024/09/dots.png"
}
}

为所有页面添加背景图片样式。

区块特定样式

您可以为单个区块应用特定样式，如阴影、排版和边框。

边框键：

• color — 定义边框的颜色。
• radius — 为圆角设置边框半径。
• style — 指定边框的样式（如实心、虚线）。
• width — 控制边框的宽度。
• top, right, bottom, left — 允许您为每一侧设置单独的边框样式。

例如，下面的内容会在整个页面周围设置一个 20px 的红色实心边框：

"border": {
"color": "#ff0000",
"width": "20px",
"style": "solid"
}

为所有页面添加边框样式

您还可以为特定区块、元素或根指定自定义 CSS。例如，下面的代码为表格块应用了红色文本颜色：

"border": {
"color": "#ff0000",
"width": "20px",
"style": "solid"
}

为所有表格添加文本颜色样式。

颜色样式

color 属性允许你控制背景、渐变和文本颜色设置：

• background — 设置区块或元素的背景颜色。
• gradient — 为区块定义背景渐变色。
• text — 控制文本的颜色。

下面的示例为每个页面的每个元素设置了黑色背景和白色文本：

"color": {
"background": "#000000",
"text": "#ffffff"
}

为所有页面设置文本和背景颜色样式。

CSS

通过 css 属性，你可以将自定义样式附加到特定类，从而对主题样式进行更精细的控制。

示例：为 wp-block-template-parts 和 wp-block-button 应用自定义样式，并为按钮添加悬停效果：

"css": ".wp-block-template-part { background-color: #777777; padding: 20px; } .wp-block-button__link:hover { background-color: #ffffff; color: #000000; }"

显示页眉中所有按钮的文本和背景样式都处于悬停状态。

如您所见，页眉和页脚模板部分被指定了 background-color 和 padding，而按钮的悬停状态则是白底黑字。

尺寸

通过 dimensions 属性，可以控制区块的宽度、高度和长宽比。

尺寸键：

• aspectRatios —为元素定义自定义宽高比。
• minHeight —设置区块的最小高度。

示例：为图像区块创建 3:7 的自定义纵横比：

"blocks": {
"core/image": {
"dimensions": {
"aspectRatio": "custom"
}
}
}

不过，仅有上述内容还不够。您必须在设置部分注册“自定义”样式。

"dimensions": {
"defaultAspectRatios": true,
"aspectRatios": [
{
"name": "Custom Ratio 3:7",
"slug": "custom",
"ratio": "3/7"
}
]
}

为所有图像添加自定义比例样式选项。

在这里，你可以看到“自定义比例 ”选项已经添加。如果你想移除七个默认宽高比，请从设置部分移除 "defaultAspectRatios":true 。

特定元素样式

通过 elements 属性，可以对链接、按钮或标题等特定 HTML 元素应用样式。

例如，下面的代码关闭了所有链接的文本装饰（下划线）：

"elements": {
"link": {
"typography": {
"textDecoration": "none"
}
}
}

禁用链接的文本装饰样式。

滤镜

通过 filter 属性，您可以对某些区块（如图像）应用类似 CSS 的滤镜效果（如模糊、亮度）。

示例：对图像区块应用模糊和亮度滤镜：

"blocks": {
"core/image": {
"filter": {
"duotone": "blur(5px) brightness(0.8)"
}
}
}

为所有图像添加模糊样式。

在这里，图像区块应用了模糊和亮度效果。其他可用的滤镜值包括：

• contrast — 调整元素的对比度。
• grayscale — 将元素转换为灰度。
• invert — 反转元素的颜色。
• opacity — 控制元素的透明度。
• saturate — 增加或减少颜色的饱和度。
• sepia — 为元素添加棕褐色调。

轮廓

outline 属性定义了在元素边框外绘制轮廓的样式，但不影响布局空间。

轮廓键：

• color — 设置轮廓的颜色。
• offset — 控制边框与轮廓之间的空间。
• style — 指定轮廓样式（如虚线、实线）。
• width — 设置轮廓的宽度。

示例：在按钮上应用红色圆点轮廓：

"elements": {
"button": {
"outline": {
"color": "#ff0000",
"style": "dotted",
"width": "4px"
}
}
}

为所有按钮添加轮廓样式。

阴影样式

shadow 属性允许你对区块应用方框阴影，增加元素的深度和强调效果。

示例：为所有图像添加阴影：

"blocks": {
"core/image": {
"shadow": "0 10px 20px 0 rgb(0 0 225 / 0.50)"
}
}

为所有图像添加阴影。

间距样式

spacing 属性可管理主题的 padding、margin 和区块间隙样式。

间距键：

• blockGap — 控制区之间的间隙。
• margin — 设置区块周围的边距。
• padding — 控制区块内的填充。

下面的示例设置了左右两侧的自定义填充：

"spacing": {
"padding": {
"left": "min(6.5rem, 8vw)",
"right": "min(6.5rem, 8vw)"
}
}

添加左右填充。

排版样式

typography 属性管理字体样式、大小和其他文本相关设置。

排版的常用键：

• fontFamily — 设置文本的字体家族。
• fontSize — 定义字体大小。
• fontStyle — 指定字体样式（如斜体、正体）。
• fontWeight — 控制字体的重量（粗细）。
• letterSpacing — 调整字母之间的间距。
• lineHeight — 定义行高（文本行间距）。
• textAlign — 设置文本对齐方式（如左对齐、居中对齐、右对齐）。
• textColumns — 控制文本列数。
• textDecoration — 设置文本装饰（如下划线）。
• writingMode — 定义书写模式（如水平、垂直）。
• textTransform — 控制文本的转换（如大写、小写）。

例如，您可以将所有标题的字体粗细设置为 300，并使用斜体样式：

"blocks": {
"core/heading": {
"typography": {
"fontWeight": "300",
"fontStyle": "italic"
}
}
}

所有标题都包含斜体和加粗样式属性。

模板和样板属性

这三个顶级属性用于在主题中注册自定义资产。

1. 自定义模板

templates 属性用于为各种文章类型注册自定义模板。

• name– 位于 templates 子目录中的 .html 或 .php 文件的名称。
• title– 将分配给模板的标题，以便于识别。
• postTypes– 指定模板用于呈现的内容类型（如文章、页面）。

2. 模板部分

templateParts 属性用于定义模板的可重复使用部分（如页眉、页脚）。

• name – 位于 parts 子目录中的 .html 或 .php 文件的名称。
• title – 模板部分的标题，以便于识别。
• area – 指定模板部分适用于页面的哪个部分（如header, footer, sidebar）。

3. 样板

通过 patterns 属性，你可以从 WordPress 样板目录中注册一个模式短语数组，使它们在主题中可用。

以下是注册样板的方法：

"patterns": [
"my-custom-pattern-slug"
]

使用theme.json的三个实用示例

以下是您可能希望为正在开发的主题做的几件事。

1. 添加样板

下面是如何从 WordPress 样板目录中添加两种样板。这里显示的是 “全屏封面图片库 ”样板：

"patterns": [
"fullscreen-cover-image-gallery",
"hero-banner-with-overlap-images"
]

演示从 wordpress.org 插入样板。

注意事项：

• 从样板目录中提取的模式不会显示在网站编辑器的样板部分。这些模式只能通过插入器获取。
• 在本示例中，我们包含了顶层属性 patterns（与 settings 和 styles 相比，为简洁起见，我们在之前的示例中省略了它们）。

2. 添加自定义字体

我们从 Google 字体库中下载了两个字体文件（Roboto-Regular.ttf 和 Roboto-Bold.ttf ），并将它们上传到主题的 assets/fonts/ 子目录中。

以下代码将注册这两种字体，使它们在全站范围内可用：

"settings": {
"typography": {
"fontFamilies": [
{
"fontFamily": "Roboto",
"name": "Roboto",
"slug": "roboto",
"fontFace": [
{
"fontFamily": "Roboto Regular",
"fontWeight": "400",
"fontStyle": "normal",
"src": [
"file./assets/fonts/Roboto-Regular.ttf"
]
},
{
"fontFamily": "Roboto Bold",
"fontWeight": "700",
"fontStyle": "bold",
"src": [
"file./assets/fonts/Roboto-Bold.ttf"
]      
}  
]
}
]
}
}

显示包含的 Google 字体。

3. 设置调色板

如果要限制用户使用特定的调色板，可以这样配置。(渐变和双色调也可以根据您的要求进行配置）。

例如：

"settings": {
"color": {
"custom": false,
"defaultPalette": false,
"palette": [
{
"slug": "primary",
"color": "#1e8cbe",
"name": "Primary"
},
{
"slug": "secondary",
"color": "#21759b",
"name": "Secondary"
},
{
"slug": "tertiary",
"color": "#",
"name": "Tertiary"
},
{
"slug": "accent",
"color": "#464646",
"name": "Accent"
}
]
}
}

演示自定义主题颜色。

认识这四种颜色吗？它们是 WordPress 颜色故事的一部分。

小结

本文重点介绍了 theme.json 在现代 WordPress 主题开发中的关键作用。掌握了 theme.json，你就可以完全自定义主题的视觉设计和用户界面，而无需复杂的 PHP 或 CSS 重载。

了解如何有效使用 appearanceTools 等属性，可以在构建或改进 WordPress 主题时提供更强的控制力和更高的效率，使该文件成为希望创建灵活、用户友好主题的开发人员的必备工具。