定义全局设置 | CSS-Tricks

到目前为止，我们已经花了一些时间来熟悉 theme.json，它是所有 WordPress 块主题的基础。我们涵盖了与 JSON 语法相关的各种 JSON 数据类型和常用术语。

我们将在本文中继续学习这些知识。

WordPress 块主题 CSS 和样式设置指南

我们所说的“顶层”是什么意思

我们讨论了 JSON 如何具有结构化的语法。我们可以在 theme.json 文件的基本轮廓中看到这一点

{
  "version": 2,
  "settings": {},
  "styles": {},
  "customTemplates": {},
  "templateParts": {}
}

基本轮廓中的每个对象都是文件的“顶层”。您可以将对象视为配置各种事物的部分。忽略 version，有四个顶层部分

settings: 这里我们定义 WordPress 预设和默认值；我们也可以在这里启用或禁用某些 WordPress 功能。
styles: 这里我们定义用于全局和块级主题样式的 CSS。
customTemplates: 这里我们注册新的自定义主题模板。它相当于在经典主题中添加一个新的 PHP 模板文件。
templateParts: 此部分包含可以包含在模板中的模块化部分。它相当于您通常在经典主题中看到的 parts 子文件夹。

我们大部分时间都花在了 settings 和 styles 部分。两者都提供了一种方式来配置 WordPress 块主题的全局样式。因此，让我们看看每一个以及我们可用的各种自定义主题外观的选项。

设置部分 (`settings`)

同样，这里我们配置 WordPress 功能，有点像您在经典主题的 functions.php 文件中使用的 add_theme_support 函数。

{
  "version": 2,
  "settings": {
    // etc.
  }
}

这与主题的全局样式有什么关系？一些 WordPress 功能会影响样式，例如用于填充、边距、颜色和字体的 UI 控件。如果不启用它们，就无法在网站编辑器中的全局样式 UI 中应用这些样式和其他样式。

简而言之：我们在这里定义的是 WordPress 用于向网站编辑器的全局样式设置添加主题支持的内容，这些设置在整个主题中使用。

支持的功能

WordPress 块编辑器手册提供了一个表格，概述了我们在 settings 部分中可以启用的可用功能，并将它们与等效的 add_theme_support 函数参数进行比较。

Theme JSON 设置	`add_theme_support`
`color.custom`	`custom-colors`
`color.palette`	`editor-color-palette`
`color.gradients`	`editor-gradient-presets`
`spacing.padding`	`custom-spacing`
`spacing.units`	`custom-units`
`typography.lineHeight`	`custom-line-height`
`typography.fontSizes`	`editor-font-sizes`
`useRootPaddingAwareAlignments`	N/A

例如，您在经典主题中使用 add_theme_support 来禁用自定义字体大小

<?php
add_theme_support(disable-custom-font-sizes);

theme.json 中的等效项是 settings.typography.customFontSize 属性

{
  "version": 2,
  "settings": {
    "typography": {
      "customFontSize": false;
    }
  }
}

您可以想象，这些功能中还有嵌套功能。例如，如果我们添加了对 spacing 控件的支持，那么我们可以单独启用许多与 spacing 相关的功能

{
  "version": 2,
  "settings": {
    "spacing": {
      "margin": false,
      "padding": false,
      "blockGap": null,
      "units": [ "px", "em", "rem", "vh", "vw" ]
    },
  }
}

截至 WordPress 6.1，这些是可以在 theme.json 中配置的 settings 功能

查看完整表格

设置	功能	数据类型
`border`	`radius`	布尔值
	`color`	布尔值
	`style`	布尔值
	`width`	布尔值
`color`	`custom`	布尔值
	`customDuotone`	布尔值
	`customGradient`	布尔值
	`duotone`	数组
	`gradients`	数组
	`link`	布尔值
	`palette`	数组
	`text`	布尔值
	`background`	布尔值
	`defaultGradients`	布尔值
	`defaultPalette`	布尔值
`layout`	`contentSize`	字符串
	`wideSize`	字符串
	`type`	字符串 (`default` 和 `constrained`)
`spacing`	`margin`	布尔值
	`padding`	布尔值
	`blockGap`	字符串
	`units`	数组
`typography`	`customFontSize`	布尔值
	`lineHeight`	布尔值
	`dropCap`	布尔值
	`fontStyle`	布尔值
	fontWeight	布尔值
	`letterSpacing`	布尔值
	`textDecoration`	布尔值
	`textTransform`	布尔值
	`fontSizes`	数组
	`fontFamilies`	数组

有关于将 outline 和 border 属性添加到全局样式面板的正在进行的讨论。它们在正式采用之前包含在此表中。

`appearanceTools` 简写

我知道该表显示了许多功能。配置每个设置可能会很麻烦。这就是 appearanceTools 设置发挥作用的地方。

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

将其设置为 true 将以下设置一次性启用

{
  "version": 2,
  "settings": {
    "border": {
      "color": true,
      "radius": true,
      "style": true,
      "width": true
    },
    "color": {
      "link": true
    }
    "spacing": {
      "margin": true,
      "padding": true,
      "blockGap": true,
    },
    "typography": {
      "lineHeight": true
    }
  }
}

您可以看到我们用这种方法可以节省多少行代码！但假设您想利用 appearanceTools，但要禁用其支持的功能中的一个或两个。您可以单独执行此操作以覆盖该特定设置

{
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "border": {
      "radius": false
    }
  }
}

以下屏幕截图显示了将 appearanceTools 设置为 true 如何在全局样式 UI 中公开这些控件，该屏幕截图来自默认的 Twenty Twenty-Three 主题。

Nick Diego 的 Learn WordPress 视频详细解释了 appearanceTools 属性和全局样式界面。

填充感知对齐

此功能值得一提，因为它是在 WordPress 6.1 中作为许多其他功能的一部分发布的。它是设置两个 spacing 功能的另一种快捷方式。

所以，这

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

…相当于这

{
  "version": 2,
  "settings": {
    "spacing": {
      "margin": true,
      "padding": true
    },
  }
}

useRootPaddingAwareAlignments 的真正好处在于它的名字。通过启用它，我们选择了一个功能，该功能在主题的 <body> 上定义全局填充，并允许块“超出”该填充并全宽，如果我们需要一个块跨越边缘到边缘。

查看我之前的文章以获取有关填充感知对齐的详细概述。

配置预设值

预设是全局样式功能使用的预定义值。更具体地说，它们定义了整个块主题使用的 CSS 自定义属性。

所以，假设您正在定义块主题的默认调色板，并将黑色（#000000）添加到其中

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

在后台，名为样式引擎的东西会使用这些值来生成主题的 CSS 类和自定义属性。我在之前的一篇文章中介绍了样式引擎。

样式引擎是 WordPress 6.1 中的新 API，旨在使样式的生成方式和应用位置保持一致。换句话说，它将所有可能的样式来源集中到一起，并单独负责正确生成块样式。[…] 考虑到样式可以来自多个地方，拥有一个集中的样式 API 可能是最优雅的解决方案。

当样式引擎注意到我们的 styles 时，它会创建一组预设自定义属性。例如，上面的调色板示例？它会根据我们提供的信息生成一个基于 CSS 的自定义属性。

如果我们打开 DevTools 并检查 <body> 元素，我们会看到我们的自定义属性在那里

DevTools window showing CSS custom variables on the body element.

注意自定义属性名称是如何格式化的

--wp-preset--<feature>--<slug>: <value>

因此，回到我们最初定义黑色调色板的示例

"color": {
  "palette": [
    {
      "color": "#000000",
      "name": "Base",
      "slug": "Base"
    }
  ]
}

我们可以预期在 <body> 元素上找到此自定义属性

body {
  --wp--preset--color--base: #000000;
}

我们只关注了 settings.color 预设，但我们在 settings 部分定义的几乎所有值都会产生一个自定义属性

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingSizes": [
        {
          // Creates: --wp-preset--spacing--40: 1rem
          "slug": "40",
          "size": "1rem",
          "name": "Small"
        },
        // etc.
      ]
    }
  }
}

全局预设

现在我们知道如何在 theme.json 中定义预设值，您可能想知道哪些预设可用。下表概述了截至撰写本文时的可用预设以及它们生成的预设。

设置	功能	CSS 自定义属性	CSS 类
`color`	`duotone`	N/A	N/A
	`gradients`	`--wp-preset--gradient--<preset-slug>`	`.has-<preset-slug>-<preset-category>`
	`palette`	`--wp--preset--palette--<preset-slug>`	每个值三个类 `.has-<preset-value>-color` `.has-<preset-value>-background-color` `.has-<preset-value>-border-color`
`spacing`	`spacingScal`e	N/A	N/A
	`spacingSizes`	`--wp--preset--spacing--<preset-slug>`	`.has-<preset-slug>-spacing`
`typography`	`fontSizes`	`--wp--preset--font-size--<preset-slug>`	`.has-<preset-slug>-font-size`
	`fontFamilies`	`--wp--preset--font-family--<preset-slug>`	`.has-<preset-slug>-font-family`

块预设

在 theme.json 中定义预设值时，我们可以获得更细粒度的控制。除了我们刚刚看到的全局预设之外，我们还可以在块级别定义预设。

假设我们有以下全局颜色预设

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          // --wp-preset--color--base: #ffffff
          "color": "#FFFFFF",
          "name": "Base",
          "slug": "base"
        },
        {
          // --wp-preset--color--contrast: #000000
          "color": "#000000",
          "name": "Contrast",
          "slug": "contrast"
        }
      ]
    }
  }
}

这些设置生成的自定义属性在整个主题中使用，包括块。因此，如果我们在块编辑器中向页面添加分隔符块，它将在渲染时引用相同的调色板。

但是，我们可以使用专门针对分隔符块的调色板来覆盖该调色板（或全局 settings 中的任何其他调色板）

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [ // etc. ]
    },
    "blocks": {
      "separator": {
        "color": {
          "palette": [
            {
              "color": "#F8A100",
              "name": "Orange",
              "slug": "orange"
            }
          ]
        }
      }
    }
  }
}

在此示例中，分隔符块的调色板使用单个橙色（#F8A100）颜色值覆盖了全局调色板。

自定义预设

您还可以为任何属性创建“自定义” CSS 自定义属性。除了我们迄今为止看到的 settings 功能之外，还有一个 custom 属性，我们可以在其中执行此操作。

{
  "version": 2,
  "settings": {
    "custom": {
      // etc.
    }
  }
}

样式引擎会将我们在其中定义的任何内容转换为 CSS 自定义属性，并使用 --wp--custom--<variable-name> 命名约定。

--wp--custom--<variable-name>: <value>

您在 custom 中定义的值将转换为 CSS 自定义属性，并使用 --wp--custom--<variable-name> 命名约定。

以下是从默认 Twenty Twenty-Two 主题中直接提取的自定义设置的简化示例。其中包含 typography.font-size 和 typography.line-height 的自定义设置

{
  "version": 2,
  "settings": {
    "custom": {
      "typography": {
        "font-size": {
          "huge": "clamp(2.25rem, 4vw, 2.75rem)",
          "gigantic": "clamp(2.75rem, 6vw, 3.25rem)",
          "colossal": "clamp(3.25rem, 8vw, 6.25rem)"
        },
        "line-height": {
          "tiny": 1.15,
          "small": 1.2,
          "medium": 1.4,
          "normal": 1.6
        }
      }
    }
  }
}

总结

我们了解了 theme.json 文件的 settings 部分的很多知识。我们介绍了可用的设置以及它们如何用于定义 WordPress 网站编辑器全局样式 UI 中使用的全局样式。从那里，我们了解了预设值，包括我们可以配置哪些预设值以及样式引擎如何将它们生成到 CSS 自定义属性中。

我们还没有介绍如何使用 theme.json 在块主题中定义 CSS 样式。这发生在另一个名为 styles 的顶级部分，它是本系列下一部分的重点。

WordPress 块主题 CSS 和样式设置指南

目录

我们所说的“顶层”是什么意思

设置部分 (settings)

支持的功能

appearanceTools 简写

填充感知对齐

配置预设值

全局预设

块预设

自定义预设

总结

WordPress 块主题 CSS 和样式设置指南

设置部分 (`settings`)

`appearanceTools` 简写