WordPress 5.8+ 引入了主题的编辑器控制文件 theme.json

WordPress 5.8 附带了一种新机制来配置编辑器，该机制可实现更细粒度的控制，并引入了管理未来 WordPress 版本的样式的第一步。

文章目录

全局和每个块控制设置

块的引入增加了设置机构和开发人员可能需要控制的数量。拥有配置的中心点旨在提供更加一致和完整的体验。

通过在主题的顶级目录中创建一个文件theme.json，主题可以配置现有的编辑器设置（字体大小预设，是否启用自定义颜色等）以及引入的新设置（双色调预设，是否边距和填充控件已启用等）。

这种新机制旨在接管和整合以前控制编辑器所需的所有各种add_theme_support调用。

下面的示例显示了如何禁用所有块的自定义颜色：

{
    "version": 1,
    "settings": {
        "color": {
            "custom": false
        }
    }
}

该theme.json文件的添加还为主题作者提供了一种基于每个块控制这些设置的方法——这在以前是不可能的。下面的示例显示了如何禁用所有块的自定义颜色，但为段落块启用它们：

{
    "version": 1,
    "settings": {
        "color": {
            "custom": false
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                    "custom": true
                }
            }
        }
    }
}

顶级设置将应用于支持相关设置的所有块。但是，块级设置也可以覆盖特定块的顶级设置。块由它们的块名称寻址，并且可以为核心和第三方块添加设置。

注意：为了保持向后兼容性，主题的现有的add_theme_support声明在顶级部分的适当类别中进行了改造。例如，如果主题使用add_theme_support('disable-custom-colors')，结果将等同于settings.color.custom 设置为false。如果在theme.json 设置中声明了一个设置，则该设置将优先于add_theme_support的设置.

请参阅规范文档以获取完整的功能列表和向后兼容add_theme_support.

块可以通过 `useSetting` 访问主题设置

核心块已更新以尊重来自主题的新设置theme.json。例如，如果某个块支持UI边距控件，但主题已全面禁用边距，则该 UI 控件将不会显示在编辑器中。

第三方块也可以通过在其编辑功能中使用useSetting React钩子来利用这种机制：

import { useSetting } from '@wordpress/block-editor';
// Somewhere in the block's edit function.

const isEnabled = useSetting( 'spacing.margin' );

if ( ! isEnabled ) {
    return null;
} else {
    return <ToggleControl ... />
}

请参阅useSetting的API文档。

预设的CSS类会自动创建并入队

以前，主题必须为编辑器声明预设，并分别将相应的类排入队列。

在functions.php文件中，他们会这样做：

add_theme_support(
  'editor-color-palette',
  array(  /* define color presets, including translations */
) );

然后，在style.css：

.has-<value>-color { /* ... */ }
.has-<value>-background-color { /* ... */ }
/* etc */

通过使用 theme.json，主题只需要声明他们的预设。引擎将设置翻译，并负责为编辑器和前端创建和排队相应的样式：

{
    "version": 1,
    "settings": {
        "color": {
            "palette": [
                {
                    "name": "Color name",
                    "slug": "color-slug",
                    "color": "<color-value>"
                },
                {
                    "name": "...",
                    "slug": "...",
                    "color": "..."
                }
            ]
        }
    }
}

有关预设生成的类列表，请参阅规范文档。

CSS 自定义属性

通过逐步淘汰 IE11 支持，许多 CSS 功能变得可用。这些现在可用的功能之一是 CSS 自定义属性。当主题通过 theme.json 添加预设时，引擎会将类和 CSS 自定义属性排入队列。

下面是一个例子：

{
    "version": 1,
    "settings": {
        "color": {
            "palette": [
                {
                    "name": "Black",
                    "slug": "black",
                    "color": "#000000"
                },
                {
                    "name": "White",
                    "slug": "white",
                    "color": "#ffffff"
                }
            ]
        }
    }
}

将在 CSS 中创建此输出：

/* One CSS Custom Property per preset value. */
body {
  --wp--preset--color--black: #000000;
  --wp--preset--color--white: #ffffff;
}

/* The corresponding classes for each preset value. */

.has-black-color { color: var(--wp--preset--color--black) !important; }
.has-black-background-color { background-color: var(--wp--preset--color--black) !important;  }

.has-white-color { color: var(--wp--preset--color--white) !important; }
.has-white-background-color { background-color: var(--wp--preset--color--white) !important;  }

更多示例请参见规范文档，比如如何添加和使用与预设无关的自定义属性等。

管理样式以提高协调性

主题作者面临的难题之一是在具有核心、主题和用户样式的环境中出现的冲突，以及带有可以无限组合的多个块的广泛设计区域。

该theme.json文件吸收了样式块的大部分常见用例，其目标是减少传送到浏览器的 CSS 数量、减轻冲突并在 UI 控件中为用户提供当前样式信息。这是拥有整合所有三个样式来源（核心、主题、用户）的机制的第一步，一旦用户可以在项目的后期阶段提供全局样式，这将变得更加重要。

在下面的示例中，主题为顶级和几个块提供样式：

{
    "version": 1,
    "styles": {
        "color": {
            "text": "var(--wp--preset--color--primary)"
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                    "text": "var(--wp--preset--color--secondary)"
                }
            },
            "core/group": {
                "color": {
                    "text": "var(--wp--preset--color--tertiary)"
                }
            }
        }
    }
}

它会产生以下 CSS 输出：

/* Top-level styles resolve to the body selector. */body {
  color: var(--wp--preset--color--primary );
}

/* Block styles resolve to the block selector. */
p {
  color: var(--wp--preset--color--secondary );
}
.wp-block-group {
  color: var(--wp--preset--color-tertiary );
}

任何块，包括核心块和第三方块，都可以以其名称为目标。

有关受支持样式的完整列表，请参阅规范文档。