# block.json `block.json` 文件通过使用相同的 JSON 格式块定义，在服务器端和客户端（区块编辑器）注册区块，从而简化了定义和注册区块的过程。 下图详细说明了 `block.json` 文件的基本结构。 [![打开 block.json 结构图](https://developer.wordpress.org/files/2023/11/block-json.png)](https://developer.wordpress.org/files/2023/11/block-json.png "打开 block.json 结构图")
要查看完整的区块示例及其关联的 block.json 文件，请访问 区块开发示例 GitHub 仓库。
除了简化区块注册外，使用 `block.json` 还有[诸多好处](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file)，包括提升性能。 [block.json 中的元数据](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)文档提供了关于可在 `block.json` 文件中使用的所有属性的完整指南。本文将介绍最常见的选项，它们允许您指定： - 区块的基本元数据。 - 决定区块功能、外观和输出的文件。 - 数据在区块内的存储方式。 - 区块在用户界面中的设置面板。 ## 区块的基本元数据 通过 `block.json` 属性，您可以定义区块的唯一标识方式以及在区块编辑器中显示的信息。这些属性包括： - **[`apiVersion`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#api-version):** 指定区块使用的 [API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/) 版本。除非有特定要求，否则请使用最新版本。 - **[`name`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#name):** 区块的唯一名称，包含命名空间（例如 `my-plugin/my-custom-block`）。 - **[`title`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#title):** 区块的显示标题，显示在插入器中。 - **[`category`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#category):** 区块在插入器中出现的类别。常见类别包括 `text`、`media`、`design`、`widgets` 和 `theme`。 - **[`icon`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#icon):** 在插入器中代表区块的图标。可以是 [Dashicon](https://developer.wordpress.org/resource/dashicons) 标识符或自定义 SVG 图标。 - **[`description`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#description):** 区块的简短描述，提供比标题更详细的信息。 - **[`keywords`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#keywords):** 帮助用户在搜索时找到区块的关键词数组。 - **[`textdomain`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#text-domain):** 区块的文本域，用于国际化。 ## 用于区块行为、输出或样式的文件 `block.json` 文件还允许您指定区块功能所需的关键文件： - **[`editorScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-script):** 一个或多个仅用于区块编辑器的 JavaScript 文件。 - **[`editorStyle`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-style):** 一个或多个用于在区块编辑器内设置样式的 CSS 文件。 - **[`script`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#script):** 一个或多个在区块编辑器和前端都会加载的 JavaScript 文件。 - **[`style`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style):** 一个或多个在区块编辑器和前端都会应用的 CSS 文件。 - **[`viewScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script):** 一个或多个仅用于前端的 JavaScript 文件。 对于所有这些属性，您可以提供一个[文件路径](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#wpdefinedpath)（以 `file:` 开头）、一个已使用 `wp_register_script` 或 `wp_register_style` 注册的[句柄](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#wpdefinedasset)，或者一个结合了这两种选项的数组。 此外，[`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render) 属性（[在 WordPress 6.1 中引入](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/)）指定了一个 PHP 模板文件的路径，该文件负责生成[动态渲染](/docs/getting-started/fundamentals/static-dynamic-rendering)区块的前端标记。如果未向 `register_block_type()` 函数提供 `$render_callback` 函数，则使用此方法。 ## 使用区块 `attributes` 存储数据 区块 [attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#attributes) 是分配给区块的设置或数据。它们可以决定区块的各个方面，例如其内容、布局、样式以及需要与区块结构一起存储的任何其他特定信息。如果用户更改了区块（例如修改字体大小），您需要一种方法来持久化这些更改。Attributes 就是解决方案。 注册新的区块类型时，`block.json` 的 `attributes` 属性描述了区块所需的自定义数据以及它们如何存储在数据库中。这使得区块编辑器能够正确解析这些值，并将 `attributes` 传递给区块的 `Edit` 组件和 `save` 函数。 以下是 `block.json` 中定义的三个 attributes 示例： ```json "attributes": { "fallbackCurrentYear": { "type": "string" }, "showStartingYear": { "type": "boolean" }, "startingYear": { "type": "string" } }, ``` 区块使用包含特定 JSON 类属性的 HTML 样式注释标签进行“界定”。这些界定符使得在渲染文章内容或在区块编辑器中编辑文章时，能够识别区块边界并解析区块属性。 下面的代码示例演示了区块界定符中定义的 attributes。 ```html

© 2020–2023

``` 默认情况下，所有 attributes 都会被序列化并存储在区块的界定符中，但这可以根据您的需求进行配置。查看 [理解区块属性](https://developer.wordpress.org/news/2023/09/understanding-block-attributes/) 文章以了解更多信息。 ### 读取和更新属性 这些[属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes)会被传递给块的 `Edit` React 组件以在区块编辑器中显示，传递给 `save` 函数以生成存储在数据库中的标记，并传递给块的任何服务器端渲染定义。 `Edit` 组件独特地拥有通过 [`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes) 函数修改这些属性的能力。 下图详细说明了在典型块中属性是如何存储、读取和更新的。 [![打开属性关系图](https://developer.wordpress.org/files/2023/11/attributes.png)](https://developer.wordpress.org/files/2023/11/attributes.png "打开属性关系图") _在此[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3)中，查看属性如何传递给 [`Edit`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/edit.js) 组件、[`save`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/save.js) 函数和 [`render.php`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php)。_ 有关属性以及如何在自定义块中使用它们的更多信息，请访问[属性 API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) 参考页面。 ## 使用区块支持功能启用设置与样式 许多区块（包括核心区块）都提供类似的定制选项，例如背景色、文字颜色和内边距调整。 `block.json` 中的 [`supports`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#supports) 属性允许区块声明支持一系列此类常见定制选项。启用后，区块用户便可以直接在设置侧边栏中调整颜色或内边距等设置。 利用这些预定义的区块支持功能有助于确保您的区块行为与核心区块保持一致，无需从头开始重新创建类似功能。 以下是在 `block.json` 中定义颜色支持的示例： ```json "supports": { "color": { "text": true, "link": true, "background": true } } ``` 使用区块支持功能会生成一组属性，需要手动添加到[区块的包装元素](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/)中。这确保了它们能作为区块数据的一部分被正确存储，并在生成将交付给前端的区块标记时被考虑进去。 以下代码演示了启用区块支持功能后生成的属性和 CSS 类是如何存储在区块的标记表示中的。 ```html

Hello World

``` _查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-supports-6aa4dd/src/block.json)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd)。_ 有关支持功能及其在自定义区块中使用的更多信息，请访问[支持功能 API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) 参考页面。 ## 其他资源 - [block.json 示意图](https://excalidraw.com/#json=v1GrIkGsYGKv8P14irBy6,Yy0vl8q7DTTL2VsH5Ww27A) - [属性示意图](https://excalidraw.com/#json=pSgCZy8q9GbH7r0oz2fL1,MFCLd6ddQHqi_UqNp5ZSgg)