@wordpress/blocks

“Block”（区块）是用于描述标记单元的抽象术语，这些单元组合在一起形成网页的内容或布局。这一理念将当前 WordPress 中通过短代码、自定义 HTML 和嵌入发现所实现的概念整合为一个统一的 API 和用户界面体验。

如需更多背景信息，请参阅 What Are Little Blocks Made Of?，文章来自 Make WordPress Design 博客。

了解如何为 WordPress 区块编辑器创建你的第一个区块。从设置开发环境、工具到熟悉新的开发模型，本教程涵盖了开始创建区块所需的所有知识。

安装

安装模块

npm install @wordpress/blocks --save

此包假设您的代码将在 ES2015+ 环境中运行。如果您使用的环境对这些语言特性和 API 的支持有限或完全不支持，您应该在代码中包含 @wordpress/babel-preset-default 随附的 polyfill。

API

cloneBlock

给定一个区块对象，返回该区块对象的副本，可选择合并新属性以及/或替换其内部区块。

参数

• block Block: 区块实例。
• mergeAttributes Record< string, unknown >: 区块属性。
• newInnerBlocks Block[]: 嵌套区块。

返回

• Block: 克隆的区块。

cloneSanitizedBlock

给定一个区块对象，在清理其属性的同时返回该区块对象的副本，可选择合并新属性以及/或替换其内部区块。

参数

• block Block: 区块实例。
• mergeAttributes Record< string, unknown >: 区块属性。
• newInnerBlocks Block[]: 嵌套区块。

返回

• Block: 克隆的区块。

createBlock

根据区块类型和属性返回一个区块对象。

参数

• name string: 区块名称。
• attributes Record< string, unknown >: 区块属性。
• innerBlocks Block[]: 嵌套区块。
• innerContent Array< string | null >: 与内部区块交错的静态 HTML 片段，其中 null 条目标记内部区块位置。仅适用于 Custom HTML 区块。

返回

• Block: 区块对象。

createBlocksFromInnerBlocksTemplate

给定一个 InnerBlocks 模板数组或区块对象数组，从中返回创建的区块数组。它处理将 InnerBlocks 作为区块的情况，将其转换为适当的格式以继续递归处理。

参数

• innerBlocksOrTemplate Array< Block | TemplateBlock >: 嵌套区块或 InnerBlocks 模板。

返回

• Block[]: 区块对象数组。

doBlocksMatchTemplate

通过比较区块名称来检查区块列表是否与模板匹配。

参数

• blocks Block[]: 区块列表。
• template TemplateItem[]: 区块模板。

返回

• boolean: 区块列表是否与模板匹配。

findTransform

给定一组转换规则，返回优先级最高的转换规则，其中谓词函数返回真值。优先级较高的转换规则具有较低的优先级值（即在优先级顺序中排在前面）。如果转换规则集为空或谓词函数对所有条目都返回假值，则返回 null。

参数

• transforms T[]: 要搜索的转换规则。
• predicate ( transform: T ) => boolean: 在匹配的转换规则上返回 true 的函数。

返回

• T | null: 优先级最高的转换规则候选项。

getBlockAttributes

根据其类型返回已注册区块节点的区块属性。

参数

• blockTypeOrName string | BlockType: 区块类型或名称。
• innerHTML string | Node | undefined: 原始区块内容。
• attributes Record< string, unknown >: 已知的区块属性（来自分隔符）。

返回

• Record< string, unknown >: 所有区块属性。

getBlockAttributesNamesByRole

按 role 过滤区块属性并返回它们的名称。

参数

• name string: 区块属性的名称。
• role string: 区块属性的角色。

返回

• string[]: 具有提供角色的属性名称。

getBlockBindingsSource

根据其名称返回已注册的区块绑定源。

参数

• name string: 区块绑定源名称。

返回

• BlockBindingsSource | undefined: 区块绑定源。

日志

6.7.0 在 WordPress 核心中引入。

getBlockBindingsSources

返回所有已注册的区块绑定源。

返回

• Record< string, BlockBindingsSource >: 区块绑定源。

日志

6.7.0 在 WordPress 核心中引入。

getBlockContent

给定一个区块对象，返回该区块的内部 HTML 标记。

参数

• block Block: 区块实例。

返回

• string: HTML。

getBlockDefaultClassName

根据其名称返回区块的默认类名。

参数

• blockName string: 区块名称。

返回

• string: 区块的默认类。

getBlockFromExample

未记录的声明。

getBlockMenuDefaultClassName

根据其名称返回区块的默认菜单项类名。

参数

• blockName string: 区块名称。

返回

• string: 区块的默认菜单项类。

getBlockSupport

如果定义了某功能的区块支持值，则返回该值。

参数

• nameOrType string | BlockType: 区块名称或类型对象
• feature string: 要检索的功能
• defaultSupports unknown: 如果未明确定义时返回的默认值

返回

• unknown: 区块支持值

getBlockTransforms

返回给定转换方向的正常区块转换规则，可选地针对特定名称的区块，如果没有转换规则则返回空数组。如果未提供区块名称，则返回所有区块的转换规则。正常转换规则对象包含 blockName 作为属性。

参数

• direction 'to' | 'from': 转换方向（“to”，“from”）。
• blockTypeOrName string | BlockType: 区块类型或名称。

返回

• NormalizedBlockTransform[]: 指定方向的区块转换规则。

getBlockType

返回已注册的区块类型。

参数

• name string: 区块名称。

返回

• BlockType | undefined: 区块类型。

getBlockTypes

返回所有已注册的区块。

返回

• BlockType[]: 区块设置。

getChildBlockNames

返回包含给定区块子区块的数组。

参数

• blockName string: 区块名称（例如：“latest-posts”）。

返回

• string[]: 子区块名称数组。

getDefaultBlockName

检索默认区块名称。

返回

• string | null: 区块名称。

getFreeformContentHandlerName

检索处理非区块内容的区块名称，如果尚未定义处理程序，则返回 undefined。

返回

• string | null: 区块名称。

getGroupingBlockName

检索用于处理分组交互的区块名称。

返回

• string | null: 区块名称。

getPhrasingContentSchema

未记录的声明。

getPossibleBlockTransformations

返回作为参数接收的区块集可以转换成的区块类型数组。

参数

• blocks Block[]: 区块数组。

返回

• BlockTypeWithTransformMetadata[]: 参数中的区块可以转换到的区块类型。

getSaveContent

给定包含保存渲染实现和属性的块类型，返回要保存的静态标记。

参数

• blockTypeOrName string | BlockType | undefined | null: 块类型或名称。
• attributes Record< string, unknown >: 块属性。
• innerBlocks Block[]: 嵌套块。

返回

• string: 保存内容。

getSaveElement

给定包含保存渲染实现和属性的块类型，返回要保存的增强元素；如果期望原始 HTML，则返回字符串。

参数

• blockTypeOrName string | BlockType: 块类型或名称。
• attributes Record< string, unknown >: 块属性。
• innerBlocks Block[]: 嵌套块。

返回

• unknown: 保存元素或原始 HTML 字符串。

getUnregisteredTypeHandlerName

检索处理未注册块类型的块的名称，如果未定义任何处理器，则返回 undefined。

返回

• string | null: 块名称。

hasBlockSupport

如果块定义了某功能的支持，则返回 true，否则返回 false。

参数

• nameOrType string | BlockType: 块名称或类型对象。
• feature string: 要测试的功能。
• defaultSupports boolean: 如果未明确定义，该功能是否默认受支持。

返回

• boolean: 块是否支持该功能。

hasChildBlocks

返回一个布尔值，指示块是否有子块。

参数

• blockName string: 块的名称（例如：“latest-posts”）。

返回

• boolean: 如果块包含子块则为 true，否则为 false。

hasChildBlocksWithInserterSupport

返回一个布尔值，指示块是否具有至少一个具有插入器支持的子块。

参数

• blockName string: 块类型名称。

返回

• boolean: 如果块包含至少一个具有插入器支持的子块则为 true，否则为 false。

isReusableBlock

确定给定的块是否为可重用块。这是一种特殊的块类型，用于指向通过 API 存储的全局块。

参数

• blockOrType Block | BlockType | null | undefined: 要测试的块或块类型。

返回

• boolean: 给定的块是否为可重用块。

isTemplatePart

确定给定的块是否为模板部分。这是一种特殊的块类型，允许通过可重用的设计元素来组合页面模板。

参数

• blockOrType Block | BlockType | null | undefined: 要测试的块或块类型。

返回

• boolean: 给定的块是否为模板部分。

isUnmodifiedBlock

确定块的属性是否等于默认属性，这意味着块未被修改。

参数

• block Block: 块对象。
• role string: 可选角色，用于过滤属性以进行检查修改。

返回

• boolean: 块是否为未修改的块。

isUnmodifiedDefaultBlock

确定块是否为默认块，且其属性等于默认属性，这意味着块未被修改。

参数

• block Block: 块对象
• role string: 可选角色，用于过滤属性以进行检查修改。

返回

• boolean: 块是否为未修改的默认块。

isValidBlockContent

已弃用 请使用 validateBlock 以避免数据丢失。

如果解析后的块在给定输入内容的情况下是有效的，则返回 true。如果块在使用假设属性序列化时内容与原始值匹配，则认为该块有效。

在开发环境中，如果无效则记录到控制台。

参数

• blockTypeOrName BlockType | string: 块类型。
• attributes Record< string, unknown >: 解析后的块属性。
• originalBlockContent string: 原始块内容。

返回

• boolean: 块是否有效。

isValidIcon

检查参数是否为有效图标的函数。

参数

• icon unknown: 要检查的参数。

返回

• boolean: 如果参数是有效图标则为 true，否则为 false。

normalizeIconObject

接收由块在注册期间设置的图标，并返回一个新的标准化图标对象，以便我们可以在代码库中仅依赖一种可能的图标结构。

参数

• icon BlockTypeIcon | undefined: 块类型图标的渲染行为；可以是 Dashicon 缩写、元素或组件之一。

返回

• BlockTypeIconDescriptor: 描述图标的对象。

parse

利用基于通过解析表达式语法定义的 Gutenberg 语法的优化令牌驱动解析器，利用由块分隔符提供的常规节奏——通过 HTML 注释在语法上组成——给定一个通用 HTML 文档作为输入，返回块列表数组表示。

这是一个递归下降解析器，一次性线性扫描输入文档。它不直接递归，而是利用蹦床机制来防止栈溢出。此初始传递主要关注分离和隔离文档中序列化的块，而不是块内的内容。

相关

• https://developer.wordpress.org/block-editor/packages/packages-block-serialization-default-parser/

参数

• content string: 帖子内容。
• options ParseOptions: 处理块解析的额外选项。

返回

• Block[]: 块列表。

parseWithAttributeSchema

给定块的原始内容和属性的模式，根据其来源返回属性的值。

参数

• innerHTML string | Node | undefined: 块的原始内容。
• attributeSchema BlockAttribute: 属性的模式。

返回

• unknown: 属性值。

pasteHandler

将 HTML 字符串转换为已知块。剥离其他所有内容。

参数

• options RawHandlerOptions:
• options.HTML RawHandlerOptions[ 'HTML' ]: 要转换的 HTML。
• options.plainText RawHandlerOptions[ 'plainText' ]: 纯文本版本。
• options.mode RawHandlerOptions[ 'mode' ]: 将内容处理为块或内联内容。_ ‘AUTO’: 根据传递的内容决定。_ ‘INLINE’: 始终作为内联内容处理，并返回字符串。* ‘BLOCKS’: 始终作为块处理，并返回块数组。
• options.tagName RawHandlerOptions[ 'tagName' ]: 内容将被插入的标签。

返回

• Block[] | string: 块列表或字符串，取决于 handlerMode。

privateApis

未记录的声明。

rawHandler

将 HTML 字符串转换为已知块。

用法

import { rawHandler } from '@wordpress/blocks';

const blocks = rawHandler( { HTML: '<p>Hello</p><p>World</p>' } );

参数

• options { HTML?: string; }: 选项。
• options.HTML string: 要转换的 HTML。

返回

• Block[]: 块列表。

registerBlockBindingsSource

使用定义其行为的新块绑定源对象进行注册。注册后，该源可用于连接到受支持的块属性。

用法

import { _x } from '@wordpress/i18n';
import { registerBlockBindingsSource } from '@wordpress/blocks';

registerBlockBindingsSource( {
    name: 'plugin/my-custom-source',
    label: _x( 'My Custom Source', 'block bindings source' ),
    usesContext: [ 'postType' ],
    getValues: getSourceValues,
    setValues: updateMyCustomValuesInBatch,
    canUserEditValue: () => true,
} );

参数

• source BlockBindingsSource: 描述块绑定源的对象。

更新日志

6.7.0 在 WordPress 核心中引入。

registerBlockCollection

注册一个新的区块集合，用于在插入器中将同一命名空间下的区块进行分组。

用法

import { __ } from '@wordpress/i18n';
import { registerBlockCollection, registerBlockType } from '@wordpress/blocks';

// 注册集合。
registerBlockCollection( 'my-collection', {
    title: __( 'Custom Collection' ),
} );

// 在同一命名空间中注册一个区块，以将其添加到集合中。
registerBlockType( 'my-collection/block-name', {
    title: __( 'My First Block' ),
    edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
    save: () => <div>'Hello from the saved content!</div>,
} );

参数

• namespace string: 在插入器中按此命名空间对区块进行分组；对应于区块命名空间。
• settings { title: string; icon?: Icon; }: 区块集合设置。
• settings.title string: 在区块插入器中显示的标题。
• settings.icon Icon: 在区块插入器中显示的图标。

registerBlockStyle

为指定的区块类型注册新的区块样式。

有关将样式与 CSS 连接的更多信息，请参阅官方文档。

用法

import { __ } from '@wordpress/i18n';
import { registerBlockStyle } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
    return (
        <Button
            onClick={ () => {
                registerBlockStyle( 'core/quote', {
                    name: 'fancy-quote',
                    label: __( 'Fancy Quote' ),
                } );
            } }
        >
            { __( 'Add a new block style for core/quote' ) }
        </Button>
    );
};

参数

• blockNames string | string[]: 区块名称，例如 “core/latest-posts” 或 [“core/group”, “core/columns”]。
• styleVariation BlockStyle | BlockStyle[]: 包含 name（应用于区块的类名）和 label（向用户标识变体）的对象。

registerBlockType

注册一个新的区块，需提供唯一的名称和一个定义其行为的对象。注册后，该区块将在实现区块的任何编辑器界面中作为选项提供。

有关注册自定义区块的更深入信息，请参阅创建区块教程。

用法

import { __ } from '@wordpress/i18n';
import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'namespace/block-name', {
    title: __( 'My First Block' ),
    edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
    save: () => <div>Hello from the saved content!</div>,
} );

参数

• blockNameOrMetadata string | BlockConfiguration< Attributes >: 区块类型名称或其元数据。
• settings Partial< SettingsBlockConfiguration< Attributes > >: 区块设置。

返回

• BlockType | undefined: 如果成功注册则返回区块；否则返回 undefined。

registerBlockVariation

为指定的区块类型注册一个新的区块变体。

有关区块变体的更多信息，请参阅官方文档。

用法

import { __ } from '@wordpress/i18n';
import { registerBlockVariation } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
    return (
        <Button
            onClick={ () => {
                registerBlockVariation( 'core/embed', {
                    name: 'custom',
                    title: __( 'My Custom Embed' ),
                    attributes: { providerNameSlug: 'custom' },
                } );
            } }
         >
             __( 'Add a custom variation for core/embed' ) }
        </Button>
    );
};

参数

• blockName string: 区块名称（示例：“core/columns”）。
• variation BlockVariation | BlockVariation[]: 描述区块变体的对象。

sanitizeBlockAttributes

确保 attributes 仅包含由区块类型定义的值，并为缺失的属性合并默认值。

参数

• name string: 区块名称。
• attributes Record< string, unknown >: 区块属性。

返回

• Record< string, unknown >: 经过清理的属性。

serialize

接受一个或多个区块，并返回序列化后的帖子内容。

参数

• blocks Block | Block[]: 要序列化的区块。
• options BlockSerializationOptions: 序列化选项。

返回

• string: 帖子内容。

serializeRawBlock

将区块节点序列化为原生的基于 HTML 注释的区块格式。注意：此函数旨在重新序列化由有效解析器解析的区块，并跳过任何验证步骤。这并非用于内存中区块的通用序列化函数。对于大多数用途，请参阅 @wordpress/blocks 包中提供的以下函数：

相关

• serializeBlock
• serialize 有关由有效解析器返回的区块节点格式的更多信息：
• @wordpress/block-serialization-default-parser 包
• @wordpress/block-serialization-spec-parser 包

参数

• rawBlock RawBlock: 由有效解析器返回的区块节点。
• options [SerializeRawBlockOptions]: 序列化选项。

返回

• string: 表示区块的 HTML 字符串。

setCategories

设置区块类别。

用法

import { __ } from '@wordpress/i18n';
import { store as blocksStore, setCategories } from '@wordpress/blocks';
import { useSelect } from '@wordpress/data';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
    // 获取当前类别列表。
    const blockCategories = useSelect(
        ( select ) => select( blocksStore ).getCategories(),
        []
    );

    return (
        <Button
            onClick={ () => {
                // 在现有列表中添加自定义类别。
                setCategories( [
                    ...blockCategories,
                    { title: 'Custom Category', slug: 'custom-category' },
                ] );
            } }
        >
            { __( 'Add a new custom block category' ) }
        </Button>
    );
};

参数

• categories BlockCategory[]: 区块类别。

setDefaultBlockName

分配默认区块名称。

用法

import { setDefaultBlockName } from '@wordpress/blocks';

const ExampleComponent = () => {
    return (
        <Button onClick={ () => setDefaultBlockName( 'core/heading' ) }>
            { __( 'Set the default block to Heading' ) }
        </Button>
    );
};

参数

• name string: 区块名称。

setFreeformContentHandlerName

分配用于处理非区块内容的区块名称。

参数

• blockName string: 区块名称。

setGroupingBlockName

分配用于处理区块分组交互的区块名称。

此函数允许您选择另一个区块来对其他区块进行分组，而不是默认的 core/group 区块。此函数必须在组件中使用或在 DOM 完全加载时使用。请参阅 https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dom-ready/

用法

import { setGroupingBlockName } from '@wordpress/blocks';

const ExampleComponent = () => {
    return (
        <Button onClick={ () => setGroupingBlockName( 'core/columns' ) }>
            { __( 'Wrap in columns' ) }
        </Button>
    );
};

参数

• name string: 区块名称。

setUnregisteredTypeHandlerName

分配用于处理未注册区块类型的区块名称。

参数

• blockName string: 区块名称。

store

区块命名空间的存储定义。

相关

• https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

switchToBlockType

将一个或多个块转换为一个或多个新类型的块。

参数

• blocks Block[] | Block: 块数组或块对象。
• name string: 块名称。
• variationName string: 可选的目标块变体名称。

返回

• Block[] | null: 块数组或 null。

synchronizeBlocksWithTemplate

将块列表与块模板同步。

将块列表与块模板同步意味着我们遍历块，如果它与模板中相同位置的块匹配（即名称相同），则保留该块不变；如果不匹配，则根据模板创建一个新块。不在模板中的额外块将被移除。

参数

• blocks Block[]: 块列表。
• template TemplateItem[]: 块模板。

返回

• Block[]: 更新后的块列表。

unregisterBlockBindingsSource

通过提供其名称来注销块绑定源。

用法

import { unregisterBlockBindingsSource } from '@wordpress/blocks';

unregisterBlockBindingsSource( 'plugin/my-custom-source' );

参数

• name string: 要注销的块绑定源的名称。

日志记录

6.7.0 在 WordPress core 中引入。

unregisterBlockStyle

注销给定块的块样式。

用法

import { __ } from '@wordpress/i18n';
import { unregisterBlockStyle } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
    return (
        <Button
            onClick={ () => {
                unregisterBlockStyle( 'core/quote', 'plain' );
            } }
        >
            { __( 'Remove the "Plain" block style for core/quote' ) }
        </Button>
    );
};

参数

• blockName string: 块名称（例如：“core/latest-posts”）。
• styleVariationName string: 应用于块的类名。

unregisterBlockType

注销一个块。

用法

import { __ } from '@wordpress/i18n';
import { unregisterBlockType } from '@wordpress/blocks';

const ExampleComponent = () => {
    return (
        <Button
            onClick={ () => unregisterBlockType( 'my-collection/block-name' ) }
        >
            { __( 'Unregister my custom block.' ) }
        </Button>
    );
};

参数

• name string: 块名称。

返回

• BlockType | undefined: 之前的块值，如果成功注销；否则为 undefined。

unregisterBlockVariation

注销为给定块类型定义的块变体。

用法

import { __ } from '@wordpress/i18n';
import { unregisterBlockVariation } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
    return (
        <Button
            onClick={ () => {
                unregisterBlockVariation( 'core/embed', 'youtube' );
            } }
        >
            { __( 'Remove the YouTube variation from core/embed' ) }
        </Button>
    );
};

参数

• blockName string: 块的名称（例如：“core/columns”）。
• variationName string | string[]: 为该块定义的变体名称。

updateCategory

更新一个分类。

用法

import { __ } from '@wordpress/i18n';
import { updateCategory } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
    return (
        <Button
            onClick={ () => {
                updateCategory( 'text', { title: __( 'Written Word' ) } );
            } }
        >
            { __( 'Update Text category title' ) }
        </Button>
    );
};

参数

• slug string: 块分类别名。
• category Partial< BlockCategory >: 包含应更新的分类属性的对象。

validateBlock

如果解析后的块在给定的输入内容下是有效的，则返回一个 isValid 属性设置为 true 的对象。如果在使用假设的属性进行序列化时，内容与原始值匹配，则认为块是有效的。如果块无效，此函数还将返回所有验证问题。

参数

• block Block: 块对象。
• blockTypeOrName BlockType | string: 块类型或名称，如果未提供则从块中推断。

返回

• [ boolean, LoggerItem[] ]: 验证结果。

withBlockContentContext

已弃用

用于使用上下文注入 BlockContent 到包装组件的高阶组件。

参数

• OriginalComponent T: 要增强的组件。

返回

• T: 相同的组件。

为此包做出贡献

这是 Gutenberg 项目的一部分独立包。该项目组织为一个 monorepo。它由多个自包含的软件包组成，每个包都有特定的用途。此 monorepo 中的包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主要 贡献者指南。