838 lines
28 KiB
Markdown
838 lines
28 KiB
Markdown
### 前端资源加载优化
|
||
|
||
自 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',
|
||
);
|
||
``` |