Gutenberg 区块编辑器文档

title: "block.json" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Fundamentals - Getting Started - Repos

block.json

block.json 文件通过使用相同的 JSON 格式块定义，在服务器端和客户端（区块编辑器）注册区块，从而简化了定义和注册区块的过程。

下图详细说明了 block.json 文件的基本结构。

打开 block.json 结构图

要查看完整的区块示例及其关联的 block.json 文件，请访问 区块开发示例 GitHub 仓库。

除了简化区块注册外，使用 block.json 还有诸多好处，包括提升性能。

block.json 中的元数据文档提供了关于可在 block.json 文件中使用的所有属性的完整指南。本文将介绍最常见的选项，它们允许您指定：

区块的基本元数据

通过 block.json 属性，您可以定义区块的唯一标识方式以及在区块编辑器中显示的信息。这些属性包括：

用于区块行为、输出或样式的文件

block.json 文件还允许您指定区块功能所需的关键文件：

对于所有这些属性，您可以提供一个文件路径（以 file: 开头）、一个已使用 wp_register_script 或 wp_register_style 注册的句柄，或者一个结合了这两种选项的数组。

此外，render 属性（在 WordPress 6.1 中引入）指定了一个 PHP 模板文件的路径，该文件负责生成动态渲染区块的前端标记。如果未向 register_block_type() 函数提供 $render_callback 函数，则使用此方法。

使用区块 attributes 存储数据

区块 attributes 是分配给区块的设置或数据。它们可以决定区块的各个方面，例如其内容、布局、样式以及需要与区块结构一起存储的任何其他特定信息。如果用户更改了区块（例如修改字体大小），您需要一种方法来持久化这些更改。Attributes 就是解决方案。

注册新的区块类型时，block.json 的 attributes 属性描述了区块所需的自定义数据以及它们如何存储在数据库中。这使得区块编辑器能够正确解析这些值，并将 attributes 传递给区块的 Edit 组件和 save 函数。

以下是 block.json 中定义的三个 attributes 示例：

"attributes": {
    "fallbackCurrentYear": {
        "type": "string"
    },
    "showStartingYear": {
        "type": "boolean"
    },
    "startingYear": {
        "type": "string"
    }
},

区块使用包含特定 JSON 类属性的 HTML 样式注释标签进行“界定”。这些界定符使得在渲染文章内容或在区块编辑器中编辑文章时，能够识别区块边界并解析区块属性。

下面的代码示例演示了区块界定符中定义的 attributes。

<!-- wp:block-development-examples/copyright-date-block-09aac3 {"fallbackCurrentYear":"2023","showStartingYear":true,"startingYear":"2020"} -->
<p class="wp-block-block-development-examples-copyright-date-block-09aac3">© 2020–2023</p>
<!-- /wp:block-development-examples/copyright-date-block-09aac3 -->

默认情况下，所有 attributes 都会被序列化并存储在区块的界定符中，但这可以根据您的需求进行配置。查看 理解区块属性 文章以了解更多信息。

读取和更新属性

这些属性会被传递给块的 Edit React 组件以在区块编辑器中显示，传递给 save 函数以生成存储在数据库中的标记，并传递给块的任何服务器端渲染定义。

Edit 组件独特地拥有通过 setAttributes 函数修改这些属性的能力。

下图详细说明了在典型块中属性是如何存储、读取和更新的。

打开属性关系图

在此完整区块示例中，查看属性如何传递给 Edit 组件、save 函数和 render.php。

有关属性以及如何在自定义块中使用它们的更多信息，请访问属性 API 参考页面。

使用区块支持功能启用设置与样式

许多区块（包括核心区块）都提供类似的定制选项，例如背景色、文字颜色和内边距调整。

block.json 中的 supports 属性允许区块声明支持一系列此类常见定制选项。启用后，区块用户便可以直接在设置侧边栏中调整颜色或内边距等设置。

利用这些预定义的区块支持功能有助于确保您的区块行为与核心区块保持一致，无需从头开始重新创建类似功能。

以下是在 block.json 中定义颜色支持的示例：

"supports": {
    "color": {
        "text": true,
        "link": true,
        "background": true
    }
}

使用区块支持功能会生成一组属性，需要手动添加到区块的包装元素中。这确保了它们能作为区块数据的一部分被正确存储，并在生成将交付给前端的区块标记时被考虑进去。

以下代码演示了启用区块支持功能后生成的属性和 CSS 类是如何存储在区块的标记表示中的。

<!-- wp:block-development-examples/block-supports-6aa4dd {"backgroundColor":"contrast","textColor":"accent-4"} -->
<p class="wp-block-block-development-examples-block-supports-6aa4dd has-accent-4-color has-contrast-background-color has-text-color has-background">Hello World</p>
<!-- /wp:block-development-examples/block-supports-6aa4dd -->

查看上述代码的完整区块示例。

有关支持功能及其在自定义区块中使用的更多信息，请访问支持功能 API 参考页面。

其他资源