title: "注册" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Block Api - Reference Guides - Repos

注册

区块注册 API 参考。

registerBlockType

• 类型： Function

每个区块都从注册新的区块类型定义开始。要注册，你需要使用 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() 仅适用于来自单一命名空间的区块。

区块配置

• 类型: Object [ { key: value } ]

一个区块在成功注册前需要指定一些属性。这些属性通过一个配置对象来定义，该对象包含以下内容：

标题

• 类型： 字符串

这是您区块的显示标题，可使用我们的翻译函数进行翻译。标题将在插入器及编辑器的其他区域显示。

// 我们的数据对象
title: __( 'Book' );

注意： 为保持区块标题在界面中的可读性和可访问性，请尽量避免使用过长的标题。

description（可选）

• 类型： String

这是您区块的简短描述，可使用我们的翻译函数进行翻译。此描述将显示在设置侧边栏的“区块”选项卡中。

description: __( 'Block showing a Book card.' );

分类

• 类型： String [ text | media | design | widgets | theme | embed ]

区块被分组到不同类别中，以帮助用户浏览和发现它们。

核心提供的类别包括：

• text
• media
• design
• widgets
• theme
• embed

// 分配到 'widgets' 类别
category: 'widgets',

插件和主题也可以注册自定义区块类别。

icon (optional)

• Type: String | Object

An icon property should be specified to make it easier to identify a block. These can be any of WordPress' Dashicons, or a custom svg element.

// Specifying a dashicon for the block
icon: 'book-alt',

// Specifying a custom svg for the block
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>,

Note: Custom SVG icons are automatically wrapped in the wp.primitives.SVG component to add accessibility attributes (aria-hidden, role, and focusable).

An object can also be passed as icon, in this case, icon, as specified above, should be included in the src property.

Besides src the object can contain background and foreground colors, these colors will appear with the icon when they are applicable e.g.: in the inserter.

icon: {
    // Specifying a background color to appear with the icon e.g.: in the inserter.
    background: '#7e70af',
    // Specifying a color for the icon (optional: if not set, a readable color will be automatically defined)
    foreground: '#fff',
    // Specifying an icon for the block
    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>,
} ,

关键词（可选）

• 类型： Array

有时一个区块可能有别名，帮助用户在搜索时发现它。例如，一个 image 区块可能也想通过 photo 被发现。你可以通过提供一个术语数组（可以翻译）来实现。

// 通过关键词别名让区块更容易被发现。
// 这些可以被本地化，因此你的关键词可以在不同语言环境中生效。
keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],

styles (optional)

• Type: Array

Block styles can be used to provide alternative styles to block. It works by adding a class name to the block’s wrapper. Using CSS, a theme developer can target the class name for the block style if it is selected.

// Register block styles.
styles: [
    // Mark style as default.
    {
        name: 'default',
        label: __( 'Rounded' ),
        isDefault: true
    },
    {
        name: 'outline',
        label: __( 'Outline' )
    },
    {
        name: 'squared',
        label: __( 'Squared' )
    },
],

Plugins and Themes can also register custom block styles for existing blocks.

attributes（可选）

• 类型： Object

属性（attributes）为区块提供结构化数据需求。它们在序列化时可以以不同形式存在，但都在通用接口下统一声明。

// 指定我的区块属性
attributes: {
    cover: {
        type: 'string',
        source: 'attribute',
        selector: 'img',
        attribute: 'src',
    },
    author: {
        type: 'string',
        source: 'html',
        selector: '.book-author',
    },
    pages: {
        type: 'number',
    },
},

• 另请参阅：属性。

example（可选）

• 类型： Object

示例为区块提供结构化的示例数据。这些数据用于构建区块预览，当用户鼠标悬停在区块上时，会在检查器帮助面板中显示；当区块被选中时，会在样式面板中显示。

示例对象中提供的数据应与定义的属性匹配。例如：

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: {
                /* translators: example text. */
                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
},

变体（可选）

• 类型： Object[]
• 自： WordPress 5.9.0

类似于声明区块样式的方式，区块类型可以定义用户可选择的区块变体。区别在于，此字段不仅改变视觉外观，还提供了一种在插入区块时应用初始自定义属性和内部区块的方法。更多详情请参阅 区块变体 API。

supports（可选）

• 类型： Object

Supports 包含一组用于控制编辑器中功能的选项。更多详情请参阅 supports 文档。

transforms（可选）

• 类型： Object

转换规则定义了区块可以从何种形式转换而来，以及可以转换为何种形式。一个区块可以从另一个区块、短代码、正则表达式、文件或原始 DOM 节点转换而来。查看 Block Transforms API 以获取有关每种可用转换的更多信息。

parent（可选）

• 类型： Array

区块能够插入到使用 InnerBlocks 的区块中作为嵌套内容。有时，限制一个区块仅作为嵌套块可用是很有用的。例如，你可能希望只允许“加入购物车”区块在“产品”区块内部使用。

设置 parent 可以让一个区块要求自己仅在嵌套于指定区块内时才可用。

// 仅允许此区块嵌套在 Columns 区块中
parent: [ 'core/columns' ],

ancestor（可选）

• 类型： Array
• 始于： WordPress 6.0.0

ancestor 属性使一个块可以在祖先块子树中的任何位置，在指定的块类型内部使用。例如，只要 'Column' 块位于 'Comment Template' 块内的某处，就允许将 'Comment Content' 块放置在 'Column' 块内。与 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',
    }
}

区块集合

registerBlockCollection

• 类型: Function

区块可以添加到集合中，将来自同一来源的所有区块分组在一起

registerBlockCollection 接收两个参数：namespace 和一个包含 title 和 icon 的设置对象。

命名空间

• 类型： String

这应与块名称中声明的命名空间一致；即你的插件或主题的名称。

设置

标题

• 类型: String

这将在区块插入器部分显示，该部分会列出此集合中的所有区块。

图标

• 类型: Object

（可选）在区块插入器中与标题一起显示的图标。

// 注册一个区块集合
registerBlockCollection( 'my-plugin', { title: 'My Plugin' } );