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 ='';}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 文件不仅仅是设计配置。它还可以帮助添加和删除网站编辑器的功能。

下载仅供下载体验和测试学习，不得商用和正当使用。

点击下载