### 前端资源加载优化

自 WordPress 5.8 版本起，开发者可配置仅在前端渲染时加载指定区块类型的脚本与样式。此功能适用于 `block.json` 文件中的以下资源字段：

-   `script`
-   `viewScript`
-   `style`
-   `viewStyle`（WordPress 6.5.0 版本新增）

## 国际化支持

WordPress 字符串发现系统可自动翻译本文档中标记为可翻译的字段。首先需在提供区块元数据的 `block.json` 文件中设置 `textdomain` 属性。

**示例：**

```json
{
	"title": "我的区块",
	"description": "我的区块非常出色",
	"keywords": [ "出色" ],
	"textdomain": "我的插件"
}
```

### PHP 实现

在 PHP 中，当执行 `register_block_type` 时，本地化属性将在 WordPress 后端自动包裹在 `_x` 函数调用中。这些翻译会以内联脚本形式添加到插件的脚本句柄或 WordPress 核心的 `wp-block-library` 脚本句柄。

`register_block_type` 处理可翻译值的方式大致等效于以下代码段：

```php
<?php
$metadata = array(
	'title'       => _x( '我的区块', '区块标题', '我的插件' ),
	'description' => _x( '我的区块非常出色！', '区块描述', '我的插件' ),
	'keywords'    => array( _x( '出色', '区块关键词', '我的插件' ) ),
);
```

该实现遵循现有的 [get_plugin_data](https://developer.wordpress.org/reference/functions/get_plugin_data) 函数逻辑，通过解析插件内容获取元数据，并动态应用翻译。

### JavaScript 实现

在 JavaScript 中，可通过 `@wordpress/blocks` 包的 `registerBlockType` 方法，传入从 `block.json` 加载的元数据对象作为首参数。所有本地化属性会自动包裹在 `_x`（来自 `@wordpress/i18n` 包）函数调用中，其运作机制与 PHP 端类似。

**示例：**

```js
import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
	edit: Edit,
	// ...其他客户端设置
} );
```

## 向后兼容性

现有注册机制（服务端与前端）将继续生效，它将作为基于 `block.json` 注册方式的底层实现细节。

待所有细节完善后，核心区块将进行迭代迁移，第三方区块将在控制台中收到警告提示，建议重构现有区块注册 API。

以下属性将继续在客户端保持向后兼容，部分属性未来可能被替代 API 取代：

-   `edit` - 详见[编辑与保存](/docs/reference-guides/block-api/block-edit-save.md)文档
-   `save` - 详见[编辑与保存](/docs/reference-guides/block-api/block-edit-save.md)文档
-   `transforms` - 详见[转换器](/docs/reference-guides/block-api/block-registration.md#transforms-optional)文档
-   `deprecated` - 详见[废弃区块](/docs/reference-guides/block-api/block-deprecation.md)文档
-   `merge` - 当前未收录文档，用于处理多区块合并功能
-   `getEditWrapperProps` - 同样未收录文档，用于向区块编辑组件包装器注入额外属性

**示例**：

```js
import { registerBlockType } from '@wordpress/blocks';

registerBlockType( '我的插件/区块名称', {
	edit: function () {
		// 编辑定义
	},
	save: function () {
		// 保存定义
	},
	getEditWrapperProps: function () {
		// 实现逻辑
	},
} );
```

对于 WordPress 支持的[动态区块](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md)，仍可通过服务端的 [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) 函数注册 `render_callback` 属性。

# 在 block.json 中定义元数据

自 WordPress 5.8 版本起，我们建议使用 `block.json` 元数据文件作为通过 PHP（服务端）和 JavaScript（客户端）注册区块类型的标准方式。以下是一个示例 `block.json` 文件，用于为插件创建通知区块定义元数据。

**示例：**

```json
{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "my-plugin/notice",
	"title": "通知",
	"category": "text",
	"parent": [ "core/group" ],
	"icon": "star",
	"description": "显示警告、错误或成功通知...",
	"keywords": [ "警示", "消息" ],
	"version": "1.0.3",
	"textdomain": "my-plugin",
	"attributes": {
		"message": {
			"type": "string",
			"source": "html",
			"selector": ".message"
		}
	},
	"providesContext": {
		"my-plugin/message": "message"
	},
	"usesContext": [ "groupId" ],
	"selectors": {
		"root": ".wp-block-my-plugin-notice"
	},
	"supports": {
		"align": true
	},
	"styles": [
		{ "name": "default", "label": "默认", "isDefault": true },
		{ "name": "other", "label": "其他" }
	],
	"example": {
		"attributes": {
			"message": "这是一个通知！"
		}
	},
	"variations": [
		{
			"name": "example",
			"title": "示例",
			"attributes": {
				"message": "这是一个示例！"
			}
		}
	],
	"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"
}
```

## 使用元数据文件的优势

通过 JSON 格式存储区块类型时，区块定义支持在 JavaScript、PHP 和其他语言之间共享代码。而使用 `block.json` 元数据文件注册区块还能带来额外优势。

从性能角度来看，当主题支持资源懒加载时，通过 `block.json` 注册的区块将自动实现资源队列优化。在 `style` 或 `script` 属性中列出的前端 CSS 和 JavaScript 资源仅当区块出现在页面上时才会加入队列，从而减小页面体积。

此外，由于[区块类型 REST API 接口](https://developer.wordpress.org/rest-api/reference/block-types/)仅能列出在服务端注册的区块，因此建议在服务端注册区块；使用 `block.json` 文件可简化此注册过程。

[WordPress 插件目录](https://wordpress.org/plugins/)能够检测 `block.json` 文件，高亮显示插件中包含的区块，并提取其元数据。若希望将区块提交至区块目录，则插件中包含的所有区块都必须具备 `block.json` 文件，以便区块目录识别它们。

通过使用预定义的架构描述文件可改善开发体验。支持的编辑器能够提供工具提示、自动补全和架构验证等辅助功能。要使用此架构，请在 `block.json` 文件顶部添加以下内容：

```json
"$schema": "https://schemas.wp.org/trunk/block.json"
```

<div class="callout callout-info">
请查阅<a href="https://developer.wordpress.org/block-editor/getting-started/fundamentals-block-development/registration-of-a-block">区块注册文档</a>了解如何使用元数据注册区块。
</div>

## 区块 API

本节描述所有可添加到 `block.json` 文件中用于定义区块类型行为和元数据的属性。

### API 版本

-   类型：`number`
-   可选性：可选
-   本地化：不支持
-   属性：`apiVersion`
-   默认值：`1`

```json
{ "apiVersion": 3 }
```

区块所使用的 Block API 版本。最新版本为 `3`，随 WordPress 6.3 引入。

详见 [API 版本文档](/docs/reference-guides/block-api/block-api-versions.md) 获取更多详细信息。

### 编辑器脚本

-   类型：`WPDefinedAsset`|`WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`editorScript`

```json
{ "editorScript": "file:./index.js" }
```

区块类型的编辑器脚本定义。这些脚本仅会在编辑器环境中加入队列。

可以传递使用 [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) 函数注册的脚本句柄、相对于 `block.json` 文件的 JavaScript 文件路径，或包含两者混合的列表（[了解更多](#wpdefinedasset)）。

_注意：从 WordPress `6.1.0` 版本开始，支持传递编辑器脚本数组。_

### 脚本

-   类型：`WPDefinedAsset`|`WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`script`

```json
{ "script": "file:./script.js" }
```

区块类型的前端和编辑器脚本定义。这些脚本会在编辑器环境和网站前端查看内容时同时加入队列。

可以传递使用 [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) 函数注册的脚本句柄、相对于 `block.json` 文件的 JavaScript 文件路径，或包含两者混合的列表（[了解更多](#wpdefinedasset)）。

_注意：从 WordPress `6.1.0` 版本开始，支持传递脚本数组。_

### 视图脚本

-   类型：`WPDefinedAsset`|`WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`viewScript`
-   自：`WordPress 5.9.0`

```json
{ "viewScript": [ "file:./view.js", "example-shared-view-script" ] }
```

区块类型的前端脚本定义。这些脚本仅会在网站前端查看内容时加入队列。

可以传递使用 [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) 函数注册的脚本句柄、相对于 `block.json` 文件的 JavaScript 文件路径，或包含两者混合的列表（[了解更多](#wpdefinedasset)）。

_注意：从 WordPress `6.1.0` 版本开始，支持传递视图脚本数组。_

### 视图脚本模块

-   类型：`WPDefinedAsset`|`WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`viewScriptModule`
-   自：`WordPress 6.5.0`

```json
{ "viewScriptModule": [ "file:./view.js", "example-shared-script-module-id" ] }
```

区块类型的前端脚本模块定义。这些模块仅会在网站前端查看内容时加入队列。

可以传递使用 [`wp_register_script_module`](https://developer.wordpress.org/reference/functions/wp_register_script_module/) 函数注册的脚本模块 ID、相对于 `block.json` 文件的 JavaScript 模块路径，或包含两者混合的列表（[了解更多](#wpdefinedasset)）。

目前 WordPress 脚本与 WordPress 脚本模块不兼容。如果前端视图资源依赖于 WordPress 脚本，应使用 `viewScript`；如果依赖于 WordPress 脚本模块（当前为交互性 API），则应使用 `viewScriptModule`。脚本模块的[更多功能](https://core.trac.wordpress.org/ticket/60647)将逐步开放。

_注意：此功能自 WordPress `6.5.0` 版本起可用。_

### 编辑器样式

-   类型：`WPDefinedAsset`|`WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`editorStyle`

```json
{ "editorStyle": "file:./index.css" }
```

区块类型的编辑器样式定义。这些样式仅会在编辑器环境中加入队列。

可以传递使用 [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) 函数注册的样式句柄、相对于 `block.json` 文件的 CSS 文件路径，或包含两者混合的列表（[了解更多](#wpdefinedasset)）。

_注意：从 WordPress `5.9.0` 版本开始，支持传递编辑器样式数组。_

### 名称

-   类型：`字符串`
-   必需
-   是否本地化：否
-   属性：`name`

```json
{ "name": "core/heading" }
```

区块名称是用于标识区块的唯一字符串。名称必须遵循 `命名空间/区块名称` 的结构，其中命名空间是插件或主题的名称。

**注意：** 区块名称只能包含小写字母数字字符、连字符，且最多只能包含一个正斜杠用于表示插件唯一的命名空间前缀。名称必须以字母开头。

**注意：** 此名称在注释分隔符中使用，格式为 `<!-- wp:my-plugin/book -->`。属于 `core` 命名空间的区块类型在序列化时不包含命名空间。

### 标题

-   类型：`字符串`
-   必需
-   是否本地化：是
-   属性：`title`

```json
{ "title": "标题" }
```

这是区块的显示标题，可以通过翻译函数进行翻译。标题将显示在插入器及编辑器的其他区域中。

**注意：** 为了确保区块标题在用户界面中易于阅读和访问，请尽量避免使用过长的标题。

### 分类

-   类型：`字符串`
-   可选
-   是否本地化：否
-   属性：`category`

```json
{ "category": "文本" }
```

区块按分类进行分组，以帮助用户浏览和发现它们。

核心提供的分类包括：

-   文本
-   媒体
-   设计
-   小工具
-   主题
-   嵌入

插件和主题还可以注册[自定义区块分类](/docs/reference-guides/filters/block-filters.md#managing-block-categories)。

实现应预期并容忍未知分类，并提供合理的回退行为（例如使用“文本”分类）。

### 父级

-   类型：`字符串数组`
-   可选
-   是否本地化：否
-   属性：`parent`

```json
{ "parent": [ "my-block/product" ] }
```

设置 `parent` 可以让一个区块仅在嵌套于指定区块内时才可用。例如，可以允许“加入购物车”区块仅在“产品”区块内可用。

### 祖先

-   类型：`字符串数组`
-   可选
-   是否本地化：否
-   属性：`ancestor`
-   自：`WordPress 6.0.0`

```json
{ "ancestor": [ "my-block/product" ] }
```

`ancestor` 属性使区块可以在指定区块类型的子树中的任何位置使用。例如，可以在“列”区块中放置“评论内容”区块，只要“列”区块位于“评论模板”区块的子树中。与 `parent` 属性相比，指定了 `ancestor` 的区块可以放置在子树的任何位置，而指定了 `parent` 的区块必须是直接子级。

### 允许的区块

-   类型：`字符串数组`
-   可选
-   是否本地化：否
-   属性：`allowedBlocks`
-   自：`WordPress 6.5.0`

```json
{ "allowedBlocks": [ "my-block/product" ] }
```

`allowedBlocks` 指定哪些区块类型可以作为该区块的直接子级。例如，“列表”区块可以仅允许“列表项”区块作为子级。

### 图标

-   类型：`字符串`
-   可选
-   是否本地化：否
-   属性：`icon`

```json
{ "icon": "smile" }
```

应指定图标属性以便更容易识别区块。图标可以是 [WordPress 的 Dashicons](https://developer.wordpress.org/resource/dashicons/) 中的任意图标（在非 JavaScript 环境中，图标别名也可作为回退）。

**注意：** 也可以通过客户端使用 SVG 元素的源来覆盖此属性。此外，此属性可以通过 JavaScript 定义为包含背景色和前景色的对象。这些颜色将在适用时与图标一起显示，例如在插入器中。自定义 SVG 图标会自动包装在 [wp.primitives.SVG](/packages/primitives/README.md) 组件中，以添加可访问性属性（aria-hidden、role 和 focusable）。

### 描述

-   类型：`字符串`
-   可选
-   是否本地化：是
-   属性：`description`

```json
{
	"description": "引入新板块并组织内容，以帮助访客更好地浏览"
}
```

这是区块的简短描述，可以通过翻译函数进行翻译。此描述将显示在区块检查器中。

### 关键词

-   类型：`string[]`
-   可选
-   支持本地化：是
-   属性：`keywords`
-   默认值：`[]`

```json
{ "keywords": [ "keyword1", "keyword2" ] }
```

有时，一个区块可以设置别名，帮助用户在搜索时发现它。例如，图片区块可能还希望通过“照片”一词被搜索到。您可以通过提供不限数量的术语数组（这些术语会被翻译）来实现此功能。

### 版本

-   类型：`string`
-   可选
-   支持本地化：否
-   属性：`version`
-   自：`WordPress 5.8.0`

```json
{ "version": "1.0.3" }
```

区块的当前版本号，例如 1.0 或 1.0.3。这与插件版本管理类似。此字段可能与区块资源一起用于控制缓存失效，如果区块作者未提供此字段，则使用已安装的 WordPress 版本号代替。

### 文本域

-   类型：`string`
-   可选
-   支持本地化：否
-   属性：`textdomain`
-   自：`WordPress 5.7.0`

```json
{ "textdomain": "my-plugin" }
```

插件/区块的 [gettext](https://www.gnu.org/software/gettext/) 文本域。更多信息请参见[如何国际化您的插件](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/)页面中的[文本域](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#text-domains)部分。

### 属性

-   类型：`object`
-   可选
-   支持本地化：否
-   属性：`attributes`
-   默认值：`{}`

```json
{
	"attributes": {
		"cover": {
			"type": "string",
			"source": "attribute",
			"selector": "img",
			"attribute": "src"
		},
		"author": {
			"type": "string",
			"source": "html",
			"selector": ".book-author"
		}
	}
}
```

属性提供了区块的结构化数据需求。它们在序列化时可以以不同形式存在，但在通用接口下统一声明。

更多详情请参阅[属性文档](/docs/reference-guides/block-api/block-attributes.md)。

### 提供上下文

-   类型：`object`
-   可选
-   支持本地化：否
-   属性：`providesContext`
-   默认值：`{}`

以对象形式提供上下文，将上下文名称映射到区块自身的某个属性，供该类型区块的子级访问。

更多详情请参阅[区块上下文文档](/docs/reference-guides/block-api/block-context.md)。

```json
{
	"providesContext": {
		"my-plugin/recordId": "recordId"
	}
}
```

### 上下文

-   类型：`string[]`
-   可选
-   支持本地化：否
-   属性：`usesContext`
-   默认值：`[]`

要从祖先提供者继承的上下文值名称数组。

更多详情请参阅[区块上下文文档](/docs/reference-guides/block-api/block-context.md)。

```json
{
	"usesContext": [ "message" ]
}
```

### 选择器

-   类型：`object`
-   可选
-   支持本地化：否
-   属性：`selectors`
-   默认值：`{}`
-   自：`WordPress 6.3.0`

在生成 theme.json（全局样式）样式表的区块样式时使用的任何自定义 CSS 选择器，按 `root`、功能或子功能作为键。提供自定义选择器可以更精细地控制样式应用于哪些区块元素，例如，仅将排版样式应用于内部标题，而颜色样式仍应用于外部区块包装器等。

更多详情请参阅[选择器文档](/docs/reference-guides/block-api/block-selectors.md)。

```json
{
	"selectors": {
		"root": ".my-custom-block-selector",
		"color": {
			"text": ".my-custom-block-selector p"
		},
		"typography": {
			"root": ".my-custom-block-selector > h2",
			"text-decoration": ".my-custom-block-selector > h2 span"
		}
	}
}
```

### 支持功能

-   类型：`object`
-   可选
-   支持本地化：否
-   属性：`supports`
-   默认值：`{}`

包含一组用于控制编辑器中使用的功能的选项。更多详情请参阅[支持功能文档](/docs/reference-guides/block-api/block-supports.md)。

### 区块样式

-   类型：`数组`
-   可选
-   支持本地化：是（仅限 `label` 字段）
-   属性：`styles`
-   默认值：`[]`

```json
{
	"styles": [
		{ "name": "default", "label": "默认", "isDefault": true },
		{ "name": "other", "label": "其他" }
	]
}
```

区块样式可用于为区块提供替代样式，其实现原理是通过在区块包装器上添加类名。主题开发者可以利用 CSS 针对已选定的区块样式类名进行样式定制。

插件和主题还可以为现有区块注册[自定义区块样式](/docs/reference-guides/block-api/block-styles.md)。

### 示例配置

-   类型：`对象`
-   可选
-   支持本地化：否
-   属性：`example`

```json
{
	"example": {
		"attributes": {
			"message": "这是一个通知！"
		}
	}
}
```

该配置用于为区块提供结构化的示例数据。当用户将鼠标悬停在区块上时，这些数据将用于在检查器帮助面板中构建区块预览效果。

更多详细信息请参阅[示例配置文档](/docs/reference-guides/block-api/block-registration.md#example-optional)。

### 区块变体

-   类型：`对象数组|WP预定义路径`（[了解更多](#wpdefinedpath)）
-   可选
-   支持本地化：是（仅限各变体的 `title`、`description` 和 `keywords` 字段）
-   属性：`variations`
-   版本要求：`WordPress 5.9.0` 及以上

```json
{
	"variations": [
		{
			"name": "example",
			"title": "示例",
			"attributes": {
				"level": 2,
				"message": "这是一个示例！"
			},
			"scope": [ "block" ],
			"isActive": [ "level" ]
		}
	]
}
```

区块变体 API 允许一个区块拥有多个相似版本，这些版本共享某些通用功能。每个区块变体通过设置不同的初始属性或内部区块来相互区分。当插入区块时，这些属性和/或内部区块会被自动应用。

*注意：在 JavaScript 中可为 `isActive` 属性提供函数，为 `icon` 属性提供 React 元素。而在 `block.json` 文件中，这两个属性仅支持字符串类型*

从 6.7 版本开始，可以在 `block.json` 中指定一个 PHP 文件来在服务端生成区块变体列表：

```json
{ "variations": "file:./variations.php" }
```

该 PHP 文件需要返回包含区块变体的数组。从 PHP 文件返回的变体中的字符串不会自动本地化，需照常使用 `__()` 函数进行处理。

例如：

```php
<?php
// 为社交图标类区块生成变体

return array(
	array(
		'isDefault'  => true,
		'name'       => 'wordpress',
		'title'      => 'WordPress',
		'icon'       => 'wordpress',
		'attributes' => array(
			'service' => 'wordpress',
		),
		'isActive'   => array( 'service' )
	),
	array(
		'name'       => 'mail',
		'title'      => __( '邮件' ),
		'keywords'   => array(
			__( '邮箱' ),
			__( '电子邮件' )
		),
		'icon'       => 'mail',
		'attributes' => array(
			'service' => 'mail',
		),
		'isActive'   => array( 'mail' )
	),
);

```

更多详细信息请参阅[变体文档](/docs/reference-guides/block-api/block-variations.md)。

### 区块钩子

-   类型：`对象`
-   可选
-   属性：`blockHooks`
-   版本要求：`WordPress 6.4.0` 及以上

```json
{
	"blockHooks": {
		"my-plugin/banner": "after"
	}
}
```

区块钩子 API 允许区块自动插入到指定区块类型的所有实例旁，其相对位置也由被"挂钩"的区块指定。即区块可以选择插入到指定区块类型的前后，或作为其首个子区块/最后一个子区块（即分别在其子区块列表的开头或末尾添加）。被挂钩的区块将同时在前端和编辑器中显示（以便用户进行自定义）。

配置中的键是要挂钩的区块名称（`字符串`），值是要挂钩的位置（`字符串`）。请参阅[区块钩子文档](/docs/reference-guides/block-api/block-registration.md#block-hooks-optional)了解更多可用配置信息。

### 样式

-   类型：`WPDefinedAsset` | `WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`style`

```json
{ "style": [ "file:./style.css", "example-shared-style" ] }
```

区块类型的前端和编辑器样式定义。这些样式将在编辑器和前端查看内容时同时加载。

可以传递通过 [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) 函数注册的样式句柄、相对于 `block.json` 文件的 CSS 文件路径，或包含两者的混合列表（[了解更多](#wpdefinedasset)）。

*注意：从 WordPress `5.9.0` 版本开始，支持传递样式数组。*

### 查看样式

-   类型：`WPDefinedAsset` | `WPDefinedAsset[]`（[了解更多](#wpdefinedasset)）
-   可选
-   是否本地化：否
-   属性：`viewStyle`
-   自版本：`WordPress 6.5.0`

```json
{ "viewStyle": [ "file:./view.css", "example-view-style" ] }
```

区块类型的前端样式定义。这些样式仅在前端查看内容时加载。

可以传递通过 [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) 函数注册的样式句柄、相对于 `block.json` 文件的 CSS 文件路径，或包含两者的混合列表（[了解更多](#wpdefinedasset)）。

仅前端样式特别适用于交互式区块，用于样式化仅在用户执行某些操作后可见的部分，且这些样式在编辑器中永远不需要。你可以先使用 `style` 属性将所有通用样式放在一个样式表中。仅当需要特定于编辑器的样式或特定于前端的样式时，可以扩展使用 `editorStyle` 和 `viewStyle`，但仍将样式的主要通用部分保留在主样式表中。

### 渲染

-   类型：`WPDefinedPath`（[了解更多](#wpdefinedpath)）
-   可选
-   是否本地化：否
-   属性：`render`
-   自版本：`WordPress 6.1.0`

```json
{ "render": "file:./render.php" }
```

在服务器上渲染区块类型以在前端显示时使用的 PHP 文件。该文件暴露以下变量：

-   `$attributes`（`array`）：区块属性。
-   `$content`（`string`）：区块默认内容。
-   `$block`（`WP_Block`）：区块实例。

使用 `render` 定义的 `render.php` 文件的示例实现可能如下：

```php
<div <?php echo get_block_wrapper_attributes(); ?>>
	<?php echo esc_html( $attributes['label'] ); ?>
</div>
```

*注意：在服务器上渲染页面 HTML 时，此文件会为每个区块类型的实例加载。在文件中声明函数或类时，必须考虑到这一点。避免错误风险的最简单方法是从另一个文件调用共享逻辑。*

## 资源

### `WPDefinedPath`

`WPDefinedPath` 类型是字符串的子类型，其值表示相对于 `block.json` 文件位置的 JavaScript、CSS 或 PHP 文件路径。提供的路径必须以 `file:` 为前缀。此方法基于 npm 处理包的[本地路径](https://docs.npmjs.com/files/package.json#local-paths)的方式。

**示例：**

在 `block.json` 中：

```json
{
	"render": "file:./render.php"
}
```

### `WPDefinedAsset`

它扩展了 `WPDefinedPath`，适用于 JavaScript 和 CSS 文件。文件路径的替代方案可以是脚本句柄、脚本模块 ID 或样式句柄，引用使用 WordPress 辅助函数已注册的资源。

**示例：**

在 `block.json` 中：

```json
{
	"editorScript": "file:./index.js",
	"script": "file:./script.js",
	"viewScriptModule": [
		"file:./view.js",
		"example-registered-script-module-id"
	],
	"editorStyle": "file:./index.css",
	"style": [ "file:./style.css", "example-shared-style" ],
	"viewStyle": [ "file:./view.css", "example-view-style" ]
}
```

在 WordPress 环境中，当使用 PHP 注册区块时，它将自动注册在 `block.json` 文件中找到的所有脚本、脚本模块和样式，并使用文件路径而非资源句柄。

这就是为什么 `WPDefinedAsset` 类型必须提供一种方式来镜像使用 [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/)、[`wp_register_script_module`](https://developer.wordpress.org/reference/functions/wp_register_script_module/) 和 [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) 注册脚本、脚本模块和样式所需的参数，然后将这些参数作为与区块关联的句柄或脚本模块 ID。

可以提供具有以下结构的对象：

-   `handle`（`string`）- 脚本的名称。如果省略，将自动生成。
-   `dependencies`（`string[]` | `{ id: string, import?: 'dynamic'|'static' }[]`）- 此脚本依赖的已注册脚本句柄数组。脚本模块可以使用简单字符串表示静态依赖项，或使用对象形式表示动态依赖项。动态依赖项是可能在运行时使用或不使用的依赖项，通常与动态 `import('module-id')` 语法一起使用。默认值：`[]`。
-   `version`（`string` | `false` | `null`）- 指定脚本版本号的字符串（如果有），将作为查询字符串添加到 URL 中以实现缓存清除。如果版本设置为 `false`，则自动添加等于当前安装的 WordPress 版本的版本号。如果设置为 `null`，则不添加版本。默认值：`false`。

该定义存储在一个单独的 PHP 文件中，该文件以 `.asset.php` 结尾，并位于 `block.json` 中列出的 JS/CSS 文件旁边。WordPress 将通过模式匹配自动检测此文件。此选项是首选，因为预计它将与 `@wordpress/scripts` 包一起自动生成这些资源文件。

**示例：**

```
build/
├─ block.json
├─ index.js
└─ index.asset.php
```

在 `block.json` 中：

```json
{ "editorScript": "file:./index.js" }
```

在 `build/index.asset.php` 中：

```php
<?php
return array(
	'dependencies' => array(
		'react',
		'wp-blocks',
		'wp-i18n',
	),
	'version'      => '3be55b05081a63d8f9d0ecb466c42cfd',
);
```