注册

最后更新：2026-10-17 10:55:29

区块注册 API 参考。

您可以使用本页面中记录的函数仅通过 JavaScript 在客户端注册区块，但推荐的方法是使用 `block.json` 元数据文件在服务器端也使用 PHP 注册新的区块类型。有关完整信息，请参阅元数据文档

学习如何在 WordPress 区块编辑器中创建您的第一个区块。从设置开发环境、工具以及熟悉新的开发模式开始，本教程涵盖了您开始创建区块所需的所有知识。

registerBlockType

类型： Function

每个区块都通过注册一个新的区块类型定义来开始。要注册，请使用来自 wp-blocks 包的 registerBlockType 函数。该函数接受两个参数：区块 name 和区块配置对象。

区块名称

类型： String

区块的名称是一个唯一字符串，用于标识区块。名称必须结构化为 namespace/block-name，其中 namespace 是您的插件或主题的名称。

// 使用唯一名称注册我的区块
registerBlockType( '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

类型： String

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

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

注意： 为了保持您的区块标题在 UI 中可读和可访问，请尽量避免使用非常长的标题。

description（可选）

类型： String

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

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

icon（可选）

类型： String | Object

应指定图标属性以便于识别区块。这些可以是任何 WordPress Dashicons，或自定义 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）。

也可以将对象作为图标传递，在这种情况下，如上指定的 icon 应包含在 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>,
} ,

keywords（可选）

类型： Array

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

// 使用关键字别名使发现区块更容易。
// 这些可以本地化，以便您的关键字在不同区域中工作。
keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],

styles（可选）

类型： Array

区块样式可用于为区块提供替代样式。它通过向区块的包装器添加类名来工作。使用 CSS，主题开发人员可以针对所选区块样式的类名。

// 注册区块样式。
styles: [
    // 将样式标记为默认。
    {
        name: 'default',
        label: __( 'Rounded' ),
        isDefault: true
    },
    {
        name: 'outline',
        label: __( 'Outline' )
    },
    {
        name: 'squared',
        label: __( 'Squared' )
    },
],

插件和主题还可以为现有区块注册自定义区块样式。

attributes（可选）

类型： Object

属性提供区块的结构化数据需求。当它们被序列化时，它们可以以不同的形式存在，但它们在一个公共接口下共同声明。

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

参见：属性。

example（可选）

类型： Object

Example 为区块提供结构化示例数据。此数据用于构建预览，以便在用户将鼠标悬停在区块上时显示在 Inspector Help Panel 中，并在选择区块时在 Styles panel 中显示。

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

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

variations（可选）

Type: Object[]
Since: WordPress 5.9.0

与声明块样式的方式类似，块类型可以定义用户可以选择的块变体。不同之处在于，该字段提供了一种在插入块时应用初始自定义属性和内部块的方法。有关更多详细信息，请参阅 Block Variations API。

supports（可选）

Type: Object

Supports 包含一组选项，用于控制编辑器中使用的功能。有关更多详细信息，请参阅 supports 文档。

transforms（可选）

Type: Object

Transforms 提供了块可以转换自什么以及可以转换为什么的规则。块可以从另一个块、短代码、正则表达式、文件或原始 DOM 节点进行转换。有关每种可用转换的更多信息，请查看 Block Transforms API。

parent（可选）

Type: Array
Default: undefined

块可以插入到使用 InnerBlocks 作为嵌套内容的块中。有时限制块使其仅在特定位置可用很有用。例如，您可能希望允许“添加到购物车”块仅在“产品”块内可用。

当省略 parent 时，块不受父块类型的限制。将 parent 设置为块名称数组要求该块仅在嵌套在指定的块之一内部时才可用。

// Only allow this block when it is nested directly in a Columns block
parent: [ 'core/columns' ],

ancestor（可选）

Type: Array
Since: WordPress 6.0.0

ancestor 属性使块可以在祖先块子树的任何位置内指定的块类型中可用。这允许例如将“评论内容”块放置在“列”块内，只要“列”位于“评论模板”块的某个位置内。与 parent 属性相比，指定其 ancestor 的块可以放置在子树中的任何位置，而具有指定 parent 的块必须是直接子项。

// Only allow this block when it is nested at any level in a Columns block.
ancestor: [ 'core/columns' ],

allowedBlocks（可选）

Type: Array
Since: WordPress 6.5.0

设置 allowedBlocks 属性将限制哪些块类型可以作为块的直接子项进行嵌套。

// Only allow the Columns block to be nested as direct child of this block
allowedBlocks: [ 'core/columns' ],

blockHooks（可选）

Type: Object
Since: WordPress 6.4.0

Block Hooks 是一种 API，允许块自动插入到给定块类型的所有实例旁边，位置也由“挂钩”的块指定。也就是说，块可以选择在给定块类型之前或之后插入，或者作为其第一个或最后一个子项（即分别附加或追加到其子块列表）。挂钩的块将同时出现在前端和编辑器中（以允许用户进行自定义）。

键是要挂钩的块的名称 (string)，值是挂钩的位置 (string)。允许的目标值如下：

before – 在目标块之前注入。
after – 在目标块之后注入。
firstChild – 在目标容器块的第一个内部块之前注入。
lastChild – 在目标容器块的最后一个内部块之后注入。

{
    blockHooks: {
        'core/verse': 'before',
        'core/spacer': 'after',
        'core/column': 'firstChild',
        'core/group': 'lastChild',
    }
}

Block collections

registerBlockCollection

Type: Function

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

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

Namespace

Type: String

这应与块名称中声明的命名空间匹配；即您的插件或主题的名称。

Settings

Title

Type: String

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

Icon

Type: Object

(可选) 一个图标，用于在块插入器中显示在标题旁边。

// Registering a block collection
registerBlockCollection( 'my-plugin', { title: 'My Plugin' } );

注册