block.json

最后更新：2026-10-17 10:55:29

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

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

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

除了简化块的注册外，使用 block.json 还具有多种优势，包括提高性能。

块.json 中的元数据文档提供了有关可以在块的 block.json 文件中使用的所有属性的综合指南。本文将涵盖最常见的选项，允许您指定：

块的基本元数据。
规定块的功能、外观和输出的文件。
如何在块内存储数据。
用户界面中的块设置面板。

块的基本元数据

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

apiVersion: 指定块使用的 API 版本。除非有特殊要求，否则请使用最新版本。
name: 块的唯一名称，包括命名空间（例如，my-plugin/my-custom-block）。
title: 块在插入器中显示的显示标题。
category: 块在插入器中出现的类别。常见类别包括 text、media、design、widgets 和 theme。
icon: 在插入器中表示块的图标。这可以是一个 Dashicon slug 或自定义 SVG 图标。
description: 块的简短描述，提供比标题更多的上下文信息。
keywords: 关键词数组，帮助用户在搜索时找到块。
textdomain: 块的文本域，用于国际化。

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

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

editorScript: 仅在区块编辑器中使用的 JavaScript 文件或文件。
editorStyle: 用于在区块编辑器中进行样式的 CSS 文件或文件。
script: 在区块编辑器和前端中加载的 JavaScript 文件或文件。
style: 在区块编辑器和前端中应用的 CSS 文件或文件。
viewScript: 仅用于前端的 JavaScript 文件或文件。

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

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

使用块属性存储数据

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

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

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

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

块使用包含特定 JSON 样式的属性的 HTML 风格注释标签进行“分隔”。这些分隔符使得在渲染帖子内容或在区块编辑器中编辑帖子时能够识别块边界并解析块属性成为可能。

下面的代码示例演示了块分隔符中定义的属性。

<!-- 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 -->

默认情况下，所有属性都序列化为块的分隔符中存储，但可以配置以满足您的需求。查看了解块属性文章以了解更多。

读取和更新属性

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

Edit 组件唯一具备通过 setAttributes 函数修改这些属性的能力。

下图详细介绍了属性如何在典型块中存储、读取和更新。

查看属性如何传递给此Edit组件、save函数以及render.php，请参阅此完整块示例。

有关属性及其在自定义块中使用的更多信息，请访问 Attributes 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 -->

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

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