gutenbergdocs/docs/getting-started/fundamentals/block-json.md

## 补充资源

- [block.json 结构图](https://excalidraw.com/#json=v1GrIkGsYGKv8P14irBy6,Yy0vl8q7DTTL2VsH5Ww27A)
- [属性关系图](https://excalidraw.com/#json=pSgCZy8q9GbH7r0oz2fL1,MFCLd6ddQHqi_UqNp5ZSgg)

# 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 图示")

<div class="callout callout-info">
	要查看完整的区块示例及其相关的 <a href="https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-supports-6aa4dd/src/block.json"><code>block.json</code></a> 文件，请访问 <a href="https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd">区块开发示例</a> GitHub 仓库。
</div>

除了简化区块注册外，使用 `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.md)区块的前端标记。如果未向 `register_block_type()` 函数提供 `$render_callback` 函数，则使用此方法。

## 使用区块 `attributes` 存储数据

区块[属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#attributes)是分配给区块的设置或数据。它们可以决定区块的各个方面，例如其内容、布局、样式以及需要随区块结构存储的任何其他特定信息。如果用户更改了区块（例如修改字体大小），您需要一种方法来保留这些更改。属性正是解决方案。

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

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

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

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

以下代码示例展示了区块界定符中定义的属性。

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

默认情况下，所有属性都会被序列化并存储在区块的界定符中，但这可以根据您的需求进行配置。查看[理解区块属性](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
<!-- 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 -->
```

_查看[上述代码](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/) 参考页面。