371 lines
12 KiB
Markdown
371 lines
12 KiB
Markdown
## 区块集合
|
||
|
||
## `registerBlockCollection`
|
||
|
||
- **类型：** `函数`
|
||
|
||
区块可被添加至集合中，将同一来源的所有区块归组管理。
|
||
|
||
`registerBlockCollection` 接收两个参数：`namespace` 和一个包含 `title` 与 `icon` 的设置对象。
|
||
|
||
### 命名空间
|
||
|
||
- **类型：** `字符串`
|
||
|
||
此命名空间需与区块名称中声明的命名空间一致；即您的插件或主题的名称。
|
||
|
||
### 设置
|
||
|
||
#### 标题
|
||
|
||
- **类型：** `字符串`
|
||
|
||
此标题将在区块插入器的部分显示，列出此集合中的所有区块。
|
||
|
||
#### 图标
|
||
|
||
- **类型：** `对象`
|
||
|
||
（可选）在区块插入器中与标题一同显示的图标。
|
||
|
||
```js
|
||
// 注册一个区块集合
|
||
registerBlockCollection( 'my-plugin', { title: '我的插件' } );
|
||
```
|
||
|
||
# 注册
|
||
|
||
区块注册 API 参考文档。
|
||
|
||
<div class="callout callout-alert">
|
||
您可以使用本文档记录的函数仅在客户端通过 JavaScript 注册区块，但推荐的方式是同时使用服务端的 PHP 通过 `block.json` 元数据文件注册新区块类型。请参阅<a href="https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/">元数据文档获取完整信息</a>
|
||
<br/>
|
||
<a href="https://developer.wordpress.org/block-editor/getting-started/create-block/">了解如何创建您的第一个区块</a>。从搭建开发环境、熟悉工具到适应新的开发模式，本教程涵盖了开始创建区块所需掌握的所有知识。
|
||
</div>
|
||
|
||
## `registerBlockType`
|
||
|
||
- **类型：** `函数`
|
||
|
||
每个区块都从注册新的区块类型定义开始。要注册区块，您需要使用 [`wp-blocks` 包](/packages/blocks/README.md#registerBlockType) 中的 `registerBlockType` 函数。该函数接收两个参数：区块 `name` 和区块配置对象。
|
||
|
||
### 区块名称
|
||
|
||
- **类型：** `字符串`
|
||
|
||
区块名称是用于标识区块的唯一字符串。名称必须采用 `命名空间/区块名称` 的结构，其中命名空间是您的插件或主题名称。
|
||
|
||
```js
|
||
// 使用唯一名称注册我的区块
|
||
registerBlockType( 'my-plugin/book', {} );
|
||
```
|
||
|
||
_注意：_ 区块名称只能包含小写字母数字字符和连字符，且必须以字母开头。
|
||
|
||
_注意：_ 此名称在注释分隔符中使用，格式为 `<!-- wp:my-plugin/book -->`。核心提供的区块在序列化时不包含命名空间。
|
||
|
||
#### 重要提示：请谨慎选择命名空间
|
||
|
||
区块名称一旦确定后续将无法随意更改。区块名称会存储在使用该区块的每篇文章的内容中，因此更改名称需要编辑所有受影响的文章或运行数据库脚本。
|
||
|
||
#### 命名空间最佳实践
|
||
|
||
- 使用实际的插件/主题名称：`my-awesome-plugin/block-name`
|
||
- 避免使用通用名称，如 `editorial/`、`block/` 或 `create-block/`
|
||
- 为插件/主题中的所有区块使用相同的命名空间
|
||
- 确保命名空间唯一性，防止与其他插件冲突
|
||
|
||
```js
|
||
// 优秀示例
|
||
registerBlockType( 'my-company-blocks/hero', {} );
|
||
registerBlockType( 'awesome-gallery-plugin/slideshow', {} );
|
||
|
||
// 避免以下示例
|
||
registerBlockType( 'create-block/example', {} ); // 过于通用
|
||
registerBlockType( 'block/content', {} ); // 过于通用
|
||
```
|
||
|
||
_注意：_ `registerBlockCollection()` 仅适用于单一命名空间下的区块。
|
||
|
||
### 区块配置
|
||
|
||
- **类型：** `对象` [ `{ 键: 值 }` ]
|
||
|
||
区块需要指定若干属性才能成功注册。这些属性通过配置对象定义，包含以下内容：
|
||
|
||
#### title
|
||
|
||
- **类型：** `字符串`
|
||
|
||
这是区块的显示标题，可通过翻译函数进行本地化。标题将显示在插入器及编辑器的其他区域。
|
||
|
||
```js
|
||
// 数据对象示例
|
||
title: __( '书籍' );
|
||
```
|
||
|
||
_注意：_ 为确保区块标题在界面中易于阅读和访问，请尽量避免使用过长的标题。
|
||
|
||
#### description（可选）
|
||
|
||
- **类型：** `字符串`
|
||
|
||
这是区块的简短描述，可通过翻译函数进行本地化。该描述将显示在设置侧边栏的区块选项卡中。
|
||
|
||
```js
|
||
description: __( '显示书籍卡片的区块。' );
|
||
```
|
||
|
||
#### category
|
||
|
||
- **类型：** `字符串` [ text | media | design | widgets | theme | embed ]
|
||
|
||
区块按类别分组，以帮助用户浏览和发现。
|
||
|
||
核心提供的类别包括：
|
||
|
||
- text（文本）
|
||
- media（媒体）
|
||
- design（设计）
|
||
- widgets（小工具）
|
||
- theme（主题）
|
||
- embed（嵌入）
|
||
|
||
```js
|
||
// 分配到 'widgets' 类别
|
||
category: 'widgets',
|
||
```
|
||
|
||
插件和主题也可以注册[自定义区块类别](/docs/reference-guides/filters/block-filters.md#managing-block-categories)。
|
||
|
||
#### variations（可选）
|
||
|
||
- **类型：** `Object[]`
|
||
- **始于：** `WordPress 5.9.0`
|
||
|
||
与声明块样式的方式类似，块类型可以定义用户可供选择的块变体。不同之处在于，此字段不仅改变视觉外观，还提供在插入块时应用初始自定义属性和内部块的方法。更多详情请参阅[块变体 API](/docs/reference-guides/block-api/block-variations.md)。
|
||
|
||
#### supports（可选）
|
||
|
||
- **类型：** `Object`
|
||
|
||
`supports` 包含一组用于控制编辑器中使用的功能的选项。更多详情请参阅 [`supports` 文档](/docs/reference-guides/block-api/block-supports.md)。
|
||
|
||
#### transforms（可选）
|
||
|
||
- **类型：** `Object`
|
||
|
||
`transforms` 提供了块可以从哪些内容转换而来以及可以转换为哪些内容的规则。块可以从另一个块、短代码、正则表达式、文件或原始 DOM 节点转换而来。有关每个可用转换的更多信息，请参阅[块转换 API](/docs/reference-guides/block-api/block-transforms.md)。
|
||
|
||
#### parent（可选）
|
||
|
||
- **类型：** `Array`
|
||
|
||
块可以插入到使用 [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) 作为嵌套内容的块中。有时，限制块仅作为嵌套块可用是有用的。例如，您可能希望仅允许“加入购物车”块在“产品”块内使用。
|
||
|
||
设置 `parent` 可以让块要求仅在嵌套在指定块中时才可用。
|
||
|
||
```js
|
||
// 仅允许此块嵌套在 Columns 块中
|
||
parent: [ 'core/columns' ],
|
||
```
|
||
|
||
#### ancestor（可选）
|
||
|
||
- **类型：** `Array`
|
||
- **始于：** `WordPress 6.0.0`
|
||
|
||
`ancestor` 属性使块可以在指定块类型的子树中的任何位置使用。例如，只要“列”块位于“评论模板”块内的某个位置，就可以将“评论内容”块放置在“列”块中。与 `parent` 属性相比，指定了 `ancestor` 的块可以放置在子树的任何位置，而指定了 `parent` 的块必须是直接子级。
|
||
|
||
```js
|
||
// 仅允许此块在 Columns 块的任意层级中嵌套
|
||
ancestor: [ 'core/columns' ],
|
||
```
|
||
|
||
#### allowedBlocks（可选）
|
||
|
||
- **类型：** `Array`
|
||
- **始于：** `WordPress 6.5.0`
|
||
|
||
设置 `allowedBlocks` 属性将限制哪些块类型可以作为该块的直接子级嵌套。
|
||
|
||
```js
|
||
// 仅允许 Columns 块作为此块的直接子级嵌套
|
||
allowedBlocks: [ 'core/columns' ],
|
||
```
|
||
|
||
#### blockHooks（可选）
|
||
|
||
- **类型：** `Object`
|
||
- **始于：** `WordPress 6.4.0`
|
||
|
||
块钩子是一个 API，允许块自动插入到给定块类型的所有实例旁边，其相对位置也由“被钩入”的块指定。也就是说，块可以选择插入到给定块类型之前或之后，或者作为其第一个或最后一个子级（即分别在其子块列表的开头或末尾添加）。被钩入的块将同时显示在前端和编辑器中（以允许用户进行自定义）。
|
||
|
||
键是要钩入的块的名称（`string`），值是要钩入的位置（`string`）。允许的目标值包括：
|
||
|
||
- `before` – 在目标块之前注入。
|
||
- `after` – 在目标块之后注入。
|
||
- `firstChild` – 在目标容器块的第一个内部块之前注入。
|
||
- `lastChild` – 在目标容器块的最后一个内部块之后注入。
|
||
|
||
```js
|
||
{
|
||
blockHooks: {
|
||
'core/verse': 'before',
|
||
'core/spacer': 'after',
|
||
'core/column': 'firstChild',
|
||
'core/group': 'lastChild',
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 图标（可选）
|
||
|
||
- **类型：** `字符串` | `对象`
|
||
|
||
应指定图标属性以便更轻松地识别区块。图标可以是任意 [WordPress Dashicon](https://developer.wordpress.org/resource/dashicons/)，或自定义的 `svg` 元素。
|
||
|
||
```js
|
||
// 为区块指定 Dashicon
|
||
icon: 'book-alt',
|
||
|
||
// 为区块指定自定义 SVG
|
||
icon: <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>,
|
||
```
|
||
|
||
**注意：** 自定义 SVG 图标会自动包裹在 [`wp.primitives.SVG` 组件](/packages/primitives/README.md) 中，以添加可访问性属性（`aria-hidden`、`role` 和 `focusable`）。
|
||
|
||
也可以将对象作为图标传递，此时，如上所述的图标应包含在 `src` 属性中。
|
||
|
||
除了 `src`，对象还可以包含背景色和前景色，这些颜色将在适用时与图标一起显示，例如：在插入器中。
|
||
|
||
```js
|
||
icon: {
|
||
// 指定与图标一起显示的背景色，例如：在插入器中。
|
||
background: '#7e70af',
|
||
// 指定图标颜色（可选：如果未设置，将自动定义易读的颜色）
|
||
foreground: '#fff',
|
||
// 为区块指定图标
|
||
src: <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>,
|
||
} ,
|
||
```
|
||
|
||
#### 关键词（可选）
|
||
|
||
- **类型：** `数组`
|
||
|
||
有时，区块可能有别名，以帮助用户在搜索时发现它。例如，`image` 区块可能也希望通过 `photo` 被发现。您可以通过提供一组术语（可翻译）来实现。
|
||
|
||
```js
|
||
// 通过关键词别名更轻松地发现区块。
|
||
// 这些关键词可以本地化，因此您的关键词可以在不同语言环境中使用。
|
||
keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],
|
||
```
|
||
|
||
#### 样式（可选）
|
||
|
||
- **类型：** `数组`
|
||
|
||
区块样式可用于为区块提供替代样式。它通过向区块包装器添加类名来实现。使用 CSS，主题开发者可以在选中区块样式时定位该类名。
|
||
|
||
```js
|
||
// 注册区块样式。
|
||
styles: [
|
||
// 将样式标记为默认。
|
||
{
|
||
name: 'default',
|
||
label: __( 'Rounded' ),
|
||
isDefault: true
|
||
},
|
||
{
|
||
name: 'outline',
|
||
label: __( 'Outline' )
|
||
},
|
||
{
|
||
name: 'squared',
|
||
label: __( 'Squared' )
|
||
},
|
||
],
|
||
```
|
||
|
||
插件和主题还可以为现有区块注册 [自定义区块样式](/docs/reference-guides/block-api/block-styles.md)。
|
||
|
||
#### 属性（可选）
|
||
|
||
- **类型：** `对象`
|
||
|
||
属性提供了区块所需的结构化数据。它们在序列化时可以以不同形式存在，但它们在通用接口下一起声明。
|
||
|
||
```js
|
||
// 指定区块属性
|
||
attributes: {
|
||
cover: {
|
||
type: 'string',
|
||
source: 'attribute',
|
||
selector: 'img',
|
||
attribute: 'src',
|
||
},
|
||
author: {
|
||
type: 'string',
|
||
source: 'html',
|
||
selector: '.book-author',
|
||
},
|
||
pages: {
|
||
type: 'number',
|
||
},
|
||
},
|
||
```
|
||
|
||
- **参见：[属性](/docs/reference-guides/block-api/block-attributes.md)。**
|
||
|
||
#### 示例（可选）
|
||
|
||
- **类型：** `对象`
|
||
|
||
示例为区块提供了结构化的示例数据。这些数据用于构建区块的预览，当用户将鼠标悬停在区块上时，预览将显示在检查器帮助面板中；当选中区块时，预览将显示在样式面板中。
|
||
|
||
示例对象中提供的数据应与定义的属性匹配。例如：
|
||
|
||
```js
|
||
example: {
|
||
attributes: {
|
||
cover: 'https://example.com/image.jpg',
|
||
author: 'William Shakespeare',
|
||
pages: 500
|
||
},
|
||
},
|
||
```
|
||
|
||
如果未定义 `example`，则不会显示预览。因此，即使未定义任何属性，设置空的示例对象 `example: {}` 也会触发预览显示。
|
||
|
||
还可以通过 `innerBlocks` 使用内部区块扩展区块预览。例如：
|
||
|
||
```js
|
||
example: {
|
||
attributes: {
|
||
cover: 'https://example.com/image.jpg',
|
||
},
|
||
innerBlocks: [
|
||
{
|
||
name: 'core/paragraph',
|
||
attributes: {
|
||
/* 翻译示例文本。 */
|
||
content: __(
|
||
'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros eu felis.'
|
||
),
|
||
},
|
||
},
|
||
],
|
||
},
|
||
```
|
||
|
||
还可以通过 `viewportWidth` 以像素为单位定义预览容器的宽度。例如：
|
||
|
||
```js
|
||
example: {
|
||
attributes: {
|
||
cover: 'https://example.com/image.jpg',
|
||
},
|
||
viewportWidth: 800
|
||
},
|
||
``` |