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