## 区块集合 ## `registerBlockCollection` - **类型：** `函数` 区块可被添加至集合中，将同一来源的所有区块归组管理。 `registerBlockCollection` 接收两个参数：`namespace` 和一个包含 `title` 与 `icon` 的设置对象。 ### 命名空间 - **类型：** `字符串` 此命名空间需与区块名称中声明的命名空间一致；即您的插件或主题的名称。 ### 设置 #### 标题 - **类型：** `字符串` 此标题将在区块插入器的部分显示，列出此集合中的所有区块。 #### 图标 - **类型：** `对象` （可选）在区块插入器中与标题一同显示的图标。 ```js // 注册一个区块集合 registerBlockCollection( 'my-plugin', { title: '我的插件' } ); ``` # 注册 区块注册 API 参考文档。
您可以使用本文档记录的函数仅在客户端通过 JavaScript 注册区块，但推荐的方式是同时使用服务端的 PHP 通过 `block.json` 元数据文件注册新区块类型。请参阅元数据文档获取完整信息
了解如何创建您的第一个区块。从搭建开发环境、熟悉工具到适应新的开发模式，本教程涵盖了开始创建区块所需掌握的所有知识。
## `registerBlockType` - **类型：** `函数` 每个区块都从注册新的区块类型定义开始。要注册区块，您需要使用 [`wp-blocks` 包](/packages/blocks/README.md#registerBlockType) 中的 `registerBlockType` 函数。该函数接收两个参数：区块 `name` 和区块配置对象。 ### 区块名称 - **类型：** `字符串` 区块名称是用于标识区块的唯一字符串。名称必须采用 `命名空间/区块名称` 的结构，其中命名空间是您的插件或主题名称。 ```js // 使用唯一名称注册我的区块 registerBlockType( '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 图标会自动包裹在 [`wp.primitives.SVG` 组件](/packages/primitives/README.md) 中，以添加可访问性属性（`aria-hidden`、`role` 和 `focusable`）。 也可以将对象作为图标传递，此时，如上所述的图标应包含在 `src` 属性中。 除了 `src`，对象还可以包含背景色和前景色，这些颜色将在适用时与图标一起显示，例如：在插入器中。 ```js icon: { // 指定与图标一起显示的背景色，例如：在插入器中。 background: '#7e70af', // 指定图标颜色（可选：如果未设置，将自动定义易读的颜色） foreground: '#fff', // 为区块指定图标 src: , } , ``` #### 关键词（可选） - **类型：** `数组` 有时，区块可能有别名，以帮助用户在搜索时发现它。例如，`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 }, ```