WordPress开发人员需要了解的theme.json中的block属性

WordPress 中引入的全站编辑（FSE）功能凸显了theme.json文件日益增长的重要性。现在，您需要了解全新的层次和结构，以及帮助您创建设计的各种属性。特别是，如果你想创建具有独特区块的现代、灵活的 WordPress 主题，theme.json中的blocks属性是必不可少的。

在本指南中，我们将探讨theme.json中的blocks属性的来龙去脉，这样你就可以使用、设计和样式化 Block，从而创建更加动态和可定制的 WordPress 体验。

了解 theme.json 中的 block 属性

在深入了解blocks属性的复杂性之前，让我们先了解一下它在theme.json和 WordPress 主题开发中的作用。

二〇二三主题的theme.json文件

首先，theme.json是一个配置文件，可让您为主题定义全局样式和设置。通过这个“中心枢纽”，您可以控制主题外观和行为的各个方面，包括排版、颜色和布局选项。不过，它的功能远不止为你提供程序化的外观调整。

通过blocks属性，你可以对单个区块类型而不是整个网站进行细化控制。你可以为特定区块定义默认样式、设置和行为，从而确保整个主题的一致性和网站所有者的灵活性。

区块属性与全站编辑之间的关系

FSE 是一种以区块为核心构建网站的更加可视化的方法。在前端，您可以使用整个网站的大部分样式和自定义选项：

WordPress 中完整的网站编辑界面

出于以下几个原因，blocks属性是theme.json文件的重要组成部分：

• 它提供了定义区块样式和设置的标准化方法。
• 你可以从一个程序化的基础上创建具有凝聚力的设计系统。
• 无需自定义CSS，就能更好地控制区块的外观。
• 该属性可帮助你创建区块模式和模板。

开发人员可以使用blocks属性创建主题，充分利用完整的网站编辑功能。

如何构建区块属性（及其语法）

在结构和语法方面，blocks属性提供了标准化的帮助。你总是将其嵌套在settings对象中：

{
"version": 3,
"settings": {
"blocks": {
"core/paragraph": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
]
…

上例定义了段落区块的自定义字体大小。分解关键组件非常简单：

• 你可以在settings对象下嵌套blocks属性。
• 每个区块类型都有一个命名空间和名称（此处为core/paragraph）。
• 然后在对象中指定区块的设置。

这些设置包括全局样式的大部分设置。例如，它们可以包括排版、颜色、间距等。

配置全局区块设置

让我们看看如何定义全局设置，然后再看看这对 blocks 属性有何影响。这样，你就能在整个主题中建立起一致的设计基础。

{
"version": 3,
"settings": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
…

在本例中，我们定义了所有区块都可使用的全局字体大小。在 WordPress 网站编辑器中，您可以在排版>元素 >文本页面中找到这些选项：

网站编辑器中也可以访问theme.json中的大部分排版设置

您在theme.json中定义的每种字体大小都与此处的大小选项之一相关：

您可以在theme.json文件中设置字体大小预设

当然，还有很多其他方法可以从这里定制主题。我们的想法是创建一个适用于 80% 使用情况的全局设计。

使用blocks属性，你可以覆盖这些核心区块样式，以覆盖最后的 20%。网站编辑器中的样式屏幕还可以让你自定义每个区块的设计设置：

网站编辑器允许您编辑 WordPress 所有核心区块的设置

这对最终用户来说非常好，但对开发人员来说价值不大。我们的重点是使用theme.json来处理blocks属性。

如何自定义单个区块类型

虽然全局设置对于保持一致性非常重要，但真正的威力在于blocks属性的自定义范围。通过这种细粒度的设置，你可以定制特定区块的外观和行为，使其与主题设计相匹配，就像网站编辑器一样。

让我们以自定义主题的标题区块为例：

{
"version": 3,
"settings": {
"blocks": {
"core/heading": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "20px"
},
{
"name": "Medium",
"slug": "medium",
"size": "30px"
},
{
"name": "Large",
"slug": "large",
"size": "40px"
}
],
"fontWeight": "bold"
},
"color": {
"palette": [
{
"name": "Heading Primary",
"slug": "heading-primary",
"color": "#333333"
},
{
"name": "Heading Secondary",
"slug": "heading-secondary",
"color": "#666666"
}
]
…

您可以看到，这些属性反映了您如何进行全局更改。让我们总结一下我们正在做的事情：

• 我们为标题定义了特定的字体大小，并将其分配给大小标签。
• 所有标题的字体权重都是粗体。
• 这些标题还将获得自定义调色板。

这将确保我们的标题在整个设计中具有一致的外观。当我们不知道最终用户将如何使用这些元素时，我们还可以控制这些元素，这将进一步提高设计的一致性。

使用正确的命名空间和标题组合

调用区块类型时，使用正确的命名空间和标题组合至关重要。否则，你的更改将无法应用到你想要针对的区块。

每个区块都有一个命名空间和一个标题。WordPress 核心区块通常使用core命名空间。语段则是区块的名称：

…
"blocks": {
"core/image": {
…

如果需要知道某个区块的标签，可以查看其特定的 block.json 文件。你可以在 wp-includes/blocks 目录中找到该文件。这里有多个文件夹，每个文件夹都包含一个 block.json 文件。在每个文件夹中，区块的命名空间和标签应位于文件顶部附近：

block.json文件将包含每个区块的关键元数据

如果浏览这些目录，你会发现 wp-includes 目录也有自己的 theme.json 文件。虽然这可能看起来令人困惑，但解释起来却很简单。

为什么默认情况下主题.json文件包含自定义区块设置

WordPress自己的 theme.json 文件初看起来可能很奇怪，因为它不是一个主题。不过，这并非偶然。主要原因是为了支持与旧版本 WordPress 的向后兼容性。

例如，按钮区块设置了边框半径：

…
"blocks": {
"core/button": {
"border": {
"radius": true
}
},
…

其他区块也会有类似的设置，以帮助不同版本的 WordPress 保持一致。但是，如果您没有意识到这一点，就可能会造成问题。

如果你试图定义全局设置，却不知道为什么这些更改不适用于特定的区块，那么向后兼容性可能就是答案。当然，你也可以在自己的 theme.json 文件中覆盖这些设置。

使用 theme.json 开发自定义区块

theme.json 文件非常适合自定义现有的区块，但它的功能也可以扩展到自定义区块的开发。您可以利用 theme.json 为任何自定义区块定义默认样式和设置。这可以帮助你实现与主题设计的无缝整合。

不过，首先你必须构建区块本身。这超出了本文的讨论范围，但总的来说，有以下几个方面：

• 为程序区块搭建脚手架。这包括建立本地开发环境，并为整个程序区块创建文件结构。
• 更新 block.json 文件。在此，您需要更改程序区块标识并添加支持。后者是声明支持特定 WordPress 功能的方法。例如，您可以处理对齐方式、实现锚字段、使用各种排版设置等。
• 调整区块的 JavaScript 文件。index.js 和 edit.js 都需要代码来告诉WordPress区块的功能，并让它出现在网站编辑器中。

您可能还需要编辑 render.php、添加静态渲染等一系列工作。此时，你可以像使用其他区块一样，对 theme.json 进行任何风格上的修改。现在，让我们仔细看看 block.json 文件。

block.json 文件

这个文件被 WordPress 开发团队称为在服务器端和客户端注册区块的标准方式。这里包含的元数据会告诉 WordPress 有关区块类型及其支持文件的所有信息：

{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "my-plugin/notice",
"title": "Notice",
"category": "text",
"parent": [ "core/group" ],
"icon": "star",
"description": "Shows warning, error or success notices...",
"keywords": [ "alert", "message" ],
"version": "1.0.3",
"textdomain": "my-plugin",
"attributes": {
"message": {
"type": "string",
"source": "html",
"selector": ".message"
}
},
…

它类似于放在主题和插件 PHP 文件顶部的元数据。虽然该文件只使用 JSON 数据，但您仍然可以通过 PHP、JavaScript 和 CSS 共享代码：

…
"editorScript": "file:./index.js",
"script": "file:./script.js",
"viewScript": [ "file:./view.js", "example-shared-view-script" ],
"editorStyle": "file:./index.css",
"style": [ "file:./style.css", "example-shared-style" ],
"viewStyle": [ "file:./view.css", "example-view-style" ],
"render": "file:./render.php"
…

我们将在稍后的变体部分讨论这个问题。在本节的最后，您需要了解如何在 WordPress 中将自定义区块设置为默认值。有几种方法可以实现这一点。经典的方法是注册一个自定义文章类型，并在其中包含区块。不过，还有其他一些方法。

例如，你可以更新现有的文章类型，添加一个区块模板。下面是一个简单的例子：

…
function load_post_type_patterns() {
// Define an initial pattern for the 'HypnoToad' post type
$post_type_object = get_post_type_object( 'hypnoToad' );
$post_type_object->template = array(
array(
'core/block',
…

还有一种方法是调用 default_content 钩子，并使用标记定义区块：

function toad_content( $content, $post ) {
if ( $post->post_type === 'hypnoToad' ) {
$content ='<!-- wp:columns -->
<div class="wp-block-columns"><!-- wp:column →
<div class="wp-block-column"><!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph --></div>
<!-- /wp:column -->
<!-- wp:column -->
<div class="wp-block-column"><!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph --></div>
<!-- /wp:column --></div>
<!-- /wp:columns -->';
}
return $content;
}
add_filter( 'default_content', 'toad_content', 10, 2 );

当然，您不会只使用 JSON、HTML 和 PHP。您还会使用其他语言来帮助设计和交互。好消息是，WordPress 为您提供了一种简便的方法。

为您的区块使用自定义 CSS 属性

使用 theme.json 中的现有属性、元素属性和对象，您可以实现很多功能，但这并不能涵盖所有的使用情况。该文件提供的 custom 属性将帮助你创建相关的 CSS 属性：

{
"version": 3,
"settings": {
"custom": {
"toad": "hypno"
}
}
}

在这里，你需要给出一个键值对，它在前端会变成一个 CSS 变量：

body {
--wp--custom--toad: hypno;
}

请注意，变量将使用双连字符来分隔其元素。一般情况下，你总是会看到--wp--custom--，然后在末尾标记关键字。有时，你会使用驼峰式大小写定义变量和属性：

{
"version": 3,
"settings": {
"custom": {
"hypnoToad": "active"
}
}
}

在这里，WordPress 将使用连字符来分隔单词：

body {
--wp--custom--hypno-toad: active;
}

有了 custom 属性和 block.json，你就完全可以按照自己的想法来构建区块，包括你可能想包含的任何变化。

快速了解区块、样式和区块风格变体

在使用 blocks 属性设计样式之前，我们先来了解一下样式的变化。你的设计有几种不同的变化类型，而命名约定可能会让你使用错误的类型来满足自己的需求。下面是不同类型的细分：

• 区块变体。如果您的区块有替代版本（想想一个区块会显示用户设置的许多自定义链接），这就是区块变体。社交媒体区块就是一个很好的例子。
• 样式变体。这些是在全局网站上使用的 theme.json 的替代版本。我们在此不做介绍，但大多数区块主题都为各种调色板和排版设置提供了这些版本。
• 区块风格变体。它采用了风格变体的核心功能，让你可以为区块创建其他设计。

你可能想知道是使用区块变体还是区块风格变体；答案并不复杂。如果你想在 theme.json 中或使用 CSS 进行更改，那么就创建一个区块样式变体。其他任何情况都需要使用区块变体。

区块变体

对于区块样式变化，你需要使用 JavaScript 进行注册。在主题目录中创建一个文件是个好主意，但它可以放在任何地方。只需一行即可在 JavaScript 文件中注册变体：

const registerBlockVariation = ( blockName, variation )

对于blockName，你也需要在这里指定命名空间，就像使用 block 属性一样。在 variation 对象中，你将添加名称、标题、描述、变体是否默认激活等信息。要在站点编辑器中加载文件，只需调用 enqueue_block_editor_assets 钩子并在其中加载脚本即可。

区块风格变体

说到区块风格变体，你有两种选择：

• 使用 PHP 的 register_block_style() 函数。
• 创建 block-editor.js JavaScript 文件，使用与区块变体类似的registerBlockStyle()函数并调用脚本。

注册区块风格变体后，就可以使用 variations 属性来定位区块：

…
"styles": {
"blocks": {
"core/button": {
"variations": {
"outline": {
"border": {
"color": "var:preset|color|black",
"radius": "0",
"style": "solid",
"width": "3px"
},
…

这意味着你可能根本不需要任何自定义 CSS，几乎区块设计的方方面面都可以通过 blocks 属性来实现。

使用 blocks 属性从头到尾设计默认区块的样式

为了演示 blocks 属性的工作原理，让我们通过一个实际例子来了解一下。我们的网站使用了 Twenty Twenty-Four 主题，并使用了默认样式：

每个主题通常都会有不同的风格变化，以实现不同的外观

到目前为止，我们认为这看起来非常理想，不过标题和正文的颜色似乎过于相似。我们想改变其中一种或两种颜色，以区别它们。作为最终用户或网站所有者，我们可以在网站编辑器的样式边栏中解决这个问题。如果前往区块>标题，就可以单击文本元素，将颜色更改为合适的颜色：

您可以通过网站编辑器轻松更改各个区块的设置

不过，作为开发人员，您可以在 theme.json 中进行更改。与其他任何主题一样，最好的方法是创建一个子主题，以保留您所做的任何更改。这样做的第二个好处是，你的 theme.json 文件看起来会更整洁。

我们将在 wp-content/themes/ 目录中创建一个目录，并将其命名为 twentytwentyfour-child 。在此添加一个有效的 style.css 文件和一个空白的 theme.json 文件。

每个子主题目录都需要一个 style.css 文件和一个 theme.json 文件

在这里，你可以打开 JSON 文件并开始工作。

为子主题创建并填充 theme.json 文件

创建父主题和子主题的主题 .json 文件的主要区别在于文件的结构。你不需要说明模式，也不一定要把所有内容都放在 settings 对象中。在我们的例子中，我们必须使用 styles 属性：

{
"version": 3,
"styles": {
"blocks": {}
}
}

接下来，我们需要找到标题区块的命名空间和标题。官方的《核心区块参考指南》列出了所有这些内容，甚至还会告诉我们该区块支持哪些属性。指南告诉我们可以调整 color 属性的 background, gradient, link, 和 text 值。

"blocks": {
"core/heading": {
"color": {}
}
}

结构设计完成后，我们就可以开始考虑如何重新设计文字。

寻找配色方案并进行修改

现在，我们需要一种适合我们需要的颜色。Twenty Twenty-Four 默认变体的调色板非常出色，在专门的对比度检查器中进行检查后，我们就会有一些想法：

在设计主题的过程中，检查配色方案是否具有合适的可访问对比度是一个关键步骤。

接下来，我们可以在 theme.json 中为 Block 添加颜色选择。由于父版 Twenty Twenty-Four 主题使用自定义 CSS 属性来定义调色板样式，因此我们也可以在这里调用：

…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
…

如果需要知道调色板颜色的名称，可以在站点编辑器的颜色选择器中找到：

通过查看网站编辑器调色板中的颜色，可以找到该颜色的名称。

保存更改后，刷新网站，就会看到新的配色方案。如果没有，请检查是否在正确的对象中嵌套了 blocks 属性，因为这是一个常见的问题。

当我们看到网站时，文字的对比度降低了，更容易阅读了。不过，我们仍然希望看到段落区块和周围的标题之间有一些清晰度。主题的默认调色板有一些其他更大胆的颜色。我们将尝试在标题区块中使用 Accent / 3 色：

"blocks": {
"core/heading": {
"color": { "text": "var(--wp--preset--color--accent-3)" }
},
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" }
}
}

保存更改并刷新前端后，你会发现标题区块的定义更加清晰了：

前端会根据 theme.json 设置更改标题区块

这并不是编辑的终点。你甚至可以通过 theme.json 自定义网站编辑器的选项。

为区块添加属性选项

每个区块的支持决定了它在网站编辑器中的选项。例如，段落区块默认禁用下拉上限功能。

网站编辑器默认情况下不允许您选择启用下拉上限

我们可以在theme.json文件和 blocks 属性中重新启用。根据参考资料，我们可以利用排版属性启用下拉菜单页眉：

…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
"typography": { "dropCap": true }
…

保存这些更改并刷新编辑器后，您就可以使用切换下拉上限的选项了：

在 WordPress 网站编辑器中启用下沉帽（Drop Cap）功能只需通过 theme.json 文件几秒钟即可完成。

theme.json 文件不仅仅是设计配置。它还可以帮助添加和删除网站编辑器的功能。

小结

了解 theme.json 中的 block 属性是所有主题开发人员的必修课。它可以将全局设计变得更加独特、连贯和相关。完全可以使用单个核心和自定义区块设置，这有助于每个用户充分利用全站编辑功能。此外，在网站编辑器中提供这些选项，意味着最终用户可以在不使用代码的情况下自行更改，而您只需提供恒星默认选项。

关于在 theme.json 文件中使用 block 属性，您有任何问题吗？请在下面的评论区提问！