gutenbergdocs/docs/reference-guides/block-api/block-registration.md

## 区块集合

## `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
},
```