区块编辑器的数据

命名空间：core/block-editor。

选择器

areInnerBlocksControlled

检查给定区块是否具有受控的内部区块。

参数

• state Object：全局应用状态。
• clientId string：要检查的区块。

返回值

• boolean：如果区块具有受控的内部区块，则返回 true。

canEditBlock

判断是否允许编辑给定区块。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：是否允许编辑给定区块。

canInsertBlocks

判断是否允许将给定区块插入区块列表。

参数

• state Object：编辑器状态。
• clientIds string[]：要插入的区块客户端 ID。
• rootClientId ?string：可选的区块列表根客户端 ID。

返回值

• boolean：是否允许插入给定区块。

canInsertBlockType

判断是否允许将给定区块类型插入区块列表。

参数

• state Object：编辑器状态。
• blockName string：区块类型的名称，例如 ‘core/paragraph’。
• rootClientId ?string：可选的区块列表根客户端 ID。

返回值

• boolean：是否允许插入给定区块类型。

canLockBlockType

判断用户是否可以锁定/解锁给定区块类型。

参数

• state Object：编辑器状态。
• nameOrType (string|Object)：区块名称或类型对象。

返回值

• boolean：给定区块类型是否可以被锁定/解锁。

canMoveBlock

判断是否允许移动给定区块。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：是否允许移动给定区块。

canMoveBlocks

判断是否允许移动给定区块。

参数

• state Object：编辑器状态。
• clientIds string：要移动的区块客户端 ID。

返回值

• boolean：是否允许移动给定区块。

canRemoveBlock

判断是否允许删除给定区块。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：是否允许删除给定区块。

canRemoveBlocks

判断是否允许删除给定区块。

参数

• state Object：编辑器状态。
• clientIds string：要删除的区块客户端 ID。

返回值

• boolean：是否允许删除给定区块。

didAutomaticChange

如果上一次更改是自动更改，则返回 true，否则返回 false。

参数

• state Object：全局应用状态。

返回值

• boolean：上一次更改是否为自动更改。

getAdjacentBlockClientId

返回在给定参考 startClientId 和 modifier 方向下相邻区块的客户端 ID。默认 startClientId 为选中区块，方向为下一个区块。如果没有相邻区块，则返回 null。

参数

• state Object：编辑器状态。
• startClientId ?string：可选的起始区块客户端 ID，从该区块开始查找。
• modifier ?number：方向倍数（1 表示下一个，-1 表示上一个）。

返回值

• ?string：区块的客户端 ID；如果不存在，则返回 null。

getAllowedBlocks

返回内部区块子项允许插入的区块列表。

参数

• state Object：编辑器状态。
• rootClientId ?string：可选的区块列表根客户端 ID。

返回值

• Array?：允许的区块类型列表。

getBlock

根据客户端 ID 返回区块。这是该区块的已解析副本，包含其 blockName、clientId 和当前 attributes 状态。这不是区块的注册设置，注册设置必须从区块模块注册存储中获取。

getBlock 会递归遍历其内部区块，直到获取所有子区块，但有一个例外：“内部区块控制器”的子区块不属于其树，因此即使该区块在编辑器中明显具有子区块，innerBlocks 通常也会返回空。不要依赖控制器的 innerBlocks；请直接请求其子区块：

getBlock( syncedPatternClientId ).innerBlocks; // 通常为 []。
getBlocks( syncedPatternClientId ); // 该同步模板的区块。

当区块的子区块属于正在编辑实体之外的其他实体并与其同步时，该区块就是内部区块控制器。同步模板（core/block）和模板部件（core/template-part）是常见示例：它们各自拥有自己的区块，编辑这些区块会保存到该模板或模板部件，而不是保存到其所在的文章或模板。将它们的子区块排除在树外可以保持两个实体分离，因此遍历模板的区块时会在放置于其中的模板部件处停止。

areInnerBlocksControlled( clientId ) 用于判断区块是否为这种控制器。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• Object：已解析的区块对象。

getBlockAttributes

根据客户端 ID 返回区块的属性；如果不存在具有该客户端 ID 的区块，则返回 null。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• ?Object：区块属性。

getBlockCount

返回当前文章中存在的区块数量。

参数

• state Object：编辑器状态。
• rootClientId ?string：可选的区块列表根客户端 ID。

返回值

• number：文章中的区块数量。

getBlockEditingMode

返回给定区块的区块编辑模式。

模式可以是以下三个选项之一：

• 'disabled'：完全禁止编辑该区块，即无法选中该区块。
• 'contentOnly'：隐藏所有非内容界面，例如工具栏中的辅助控件、区块移动器和区块设置。
• 'default'：允许正常编辑该区块。

区块可以使用 useBlockEditingMode 钩子设置模式。

该模式会被区块的所有内部区块继承，除非它们有自己的模式。

模板锁定也可以设置模式。如果模板锁定为 'contentOnly'，且区块具有内容角色属性，则该区块的模式会被覆盖为 'contentOnly'，否则覆盖为 'disabled'。

相关

• useBlockEditingMode

参数

• state Object：全局应用状态。
• clientId string：区块客户端 ID，若为根容器则为 ''。

返回值

• BlockEditingMode：区块编辑模式。取值为 'disabled'、'contentOnly' 或 'default' 之一。

getBlockHierarchyRootClientId

给定区块客户端 ID，返回该区块所嵌套层级的根级客户端 ID；对于根级区块，返回该区块自身。

参数

• state Object：编辑器状态。
• clientId string：要查找根客户端 ID 的区块。

返回值

• string：根客户端 ID

getBlockIndex

返回与指定客户端 ID 对应的区块在区块顺序中的索引；如果区块不存在，则返回 -1。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• number：区块在顺序中的索引。

getBlockInsertionPoint

返回插入提示的位置。默认为最后一个索引。

参数

• state Object：编辑器状态。

返回值

• Object：包含 rootClientId、index 的插入点对象。

getBlockListSettings

返回区块的区块列表设置（如果存在）。

参数

• state Object：编辑器状态。
• clientId ?string：区块客户端 ID。

返回值

• ?Object：该区块的区块设置（如果已设置）。

getBlockMode

返回区块的编辑模式；如果未显式指定，则默认为“visual”。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• Object：区块编辑模式。

getBlockName

根据区块客户端 ID 返回区块名称；如果不存在该客户端 ID 对应的区块，则返回 null。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• string：区块名称。

getBlockNamesByClientId

给定区块客户端 ID 数组，返回对应的区块名称数组。

参数

• state Object：编辑器状态。
• clientIds string[]：要返回区块名称的客户端 ID。

返回值

• string[]：区块名称。

getBlockOrder

返回一个数组，包含编辑器中所有区块客户端 ID，并按其显示顺序排列。可选接受区块列表的根客户端 ID，用于返回该列表的顺序，默认为顶层区块顺序。

参数

• state Object：编辑器状态。
• rootClientId ?string：区块列表的可选根客户端 ID。

返回值

• Array：编辑器区块的有序客户端 ID。

getBlockParents

给定区块客户端 ID，返回其所有父级从上到下的列表。

参数

• state Object：编辑器状态。
• clientId string：要从中查找根客户端 ID 的区块。
• ascending boolean：从下到上（true）或从上到下（false）对结果排序。

返回值

• Array：父级区块的客户端 ID。

getBlockParentsByBlockName

给定区块客户端 ID 和区块名称，返回其所有父级从上到下的列表，并按给定名称进行过滤。例如，如果传入 ‘core/group’ 作为区块名称，则仅返回为 group 区块的父级。如果传入 [ 'core/group', 'core/cover'] 作为区块名称，则返回为 group 区块和 cover 区块的父级。

参数

• state Object：编辑器状态。
• clientId string：要从中查找根客户端 ID 的区块。
• blockName string|string[]：要过滤的一个或多个区块名称。
• ascending boolean：从下到上（true）或从上到下（false）对结果排序。

返回值

• Array：父级区块的客户端 ID。

getBlockRootClientId

给定区块客户端 ID，返回嵌套该区块的根区块；对于顶层区块，返回空字符串；如果区块不存在，则返回 null。

参数

• state Object：编辑器状态。
• clientId string：要从中查找根客户端 ID 的区块。

返回值

• ?string：根客户端 ID（如果存在）。

getBlocks

以数组形式返回当前正在编辑的文章中的所有区块对象，并按它们在文章中出现的顺序排列。请注意，这将排除嵌套的内部区块控制器的子区块。

参数

• state Object：编辑器状态。
• rootClientId ?string：区块列表的可选根客户端 ID。

返回值

• Object[]：文章区块。

getBlocksByClientId

给定区块客户端 ID 数组，返回对应的区块对象数组。

参数

• state Object：编辑器状态。
• clientIds string[]：要返回区块的客户端 ID。

返回值

• WPBlock[]：区块对象。

getBlocksByName

返回所有与区块名称匹配的区块。结果包括嵌套区块。

参数

• state Object：全局应用状态。
• blockName string[]：要返回客户端 ID 的一个或多个区块名称。

返回值

• Array：客户端 ID 数组，包含名称等于指定区块名称的区块。

getBlockSelectionEnd

返回当前区块选择的结束位置。该值可能为 null，并且可能表示单一区块选择或多选的结束位置。如果选择的开始位置和结束位置相同，则该选择为单一选择。

参数

• state Object：全局应用状态。

返回值

• ?string：区块选择结束位置的客户端 ID。

getBlockSelectionStart

返回当前区块选择的开始位置。该值可能为 null，并且可能表示单一区块选择或多选的开始位置。如果选择的开始位置和结束位置相同，则该选择为单一选择。

参数

• state Object：全局应用状态。

返回值

• ?string：区块选择开始位置的客户端 ID。

getBlockTransformItems

确定出现在可用区块转换列表中的项目。

每个项目对象都包含在转换列表中显示菜单项并处理其选择所需的内容。

‘frecency’ 属性是一个启发式值（https://en.wikipedia.org/wiki/Frecency），它结合了区块使用频率和最近程度。

项目按 ‘frecency’ 降序返回。

参数

• state Object：编辑器状态。
• blocks Object|Object[]：区块对象或区块对象数组。
• rootClientId ?string：区块列表的可选根客户端 ID。

返回值

• WPEditorTransformItem[]：显示在插入器中的项目。

类型定义

• WPEditorTransformItem Object

属性

• id string：项目的唯一标识符。
• name string：要创建的区块类型。
• variationName ?string：目标区块变体名称。
• title string：项目在插入器中显示的标题。
• icon string：项目在插入器中显示的 Dashicon 图标。
• isDisabled boolean：是否应阻止用户插入此项目。
• frecency number：结合频率和最近程度的启发式值。

getClientIdsOfDescendants

返回一个数组，包含给定区块的所有后代区块的客户端 ID。返回的 ID 首先按给定 ID 的顺序排序，然后按其在编辑器中出现的顺序排序。

参数

• state Object：全局应用状态。
• rootIds string|string[]：要返回后代区块的一个或多个客户端 ID。

返回值

• Array：后代区块的客户端 ID。

getClientIdsWithDescendants

返回一个数组，包含顶层区块及其任意深度后代区块（针对嵌套区块）的客户端 ID。ID 的返回顺序与它们在编辑器中显示的顺序相同。

参数

• state Object：全局应用状态。

返回值

• Array：顶层区块和后代区块的客户端 ID。

getDirectInsertBlock

返回将由区块追加器直接插入的区块。

参数

• state Object：编辑器状态。
• rootClientId ?string：区块列表的可选根客户端 ID。

返回值

• WPDirectInsertBlock|undefined：要直接插入的区块类型。

类型定义

• WPDirectInsertBlock Object

属性

• name string：区块类型。
• attributes ?Object：要传递给新创建区块的属性。

getDraggedBlockClientIds

返回正在被直接拖动的任何区块的客户端 ID。

这不包括正在被拖动的父区块的子区块。

参数

• state Object：全局应用状态。

返回值

• string[]：被拖动区块的客户端 ID 数组。

getFirstMultiSelectedBlockClientId

返回多选集合中第一个区块的客户端 ID；如果没有多选，则返回 null。

参数

• state Object：编辑器状态。

返回值

• ?string：多选集合中的第一个区块客户端 ID。

getGlobalBlockCount

返回文章中的区块总数，或指定名称的区块总数。返回的数量包含嵌套区块。

参数

• state Object：全局应用状态。
• blockName ?string：可选的区块名称，如果指定，则只统计该类型的区块。

返回值

• number：文章中的区块数量，或名称等于 blockName 的区块数量。

getHoveredBlockClientId

已弃用

返回当前悬停的区块。

getInserterItems

确定插入器中显示的项目。包括静态项目（例如常规区块类型）和动态项目（例如可重用区块）。

每个项目对象都包含在插入器中显示按钮并处理其选择所需的内容。

‘frecency’ 属性是一个启发式值（https://en.wikipedia.org/wiki/Frecency），它结合了区块使用频率和最近使用时间。

项目按 ‘utility’ 和 ‘frecency’ 降序返回。

参数

• state Object：编辑器状态。
• rootClientId ?string：可选的区块列表根客户端 ID。

返回值

• WPEditorInserterItem[]：插入器中显示的项目。

类型定义

• WPEditorInserterItem Object

属性

• id string：项目的唯一标识符。
• name string：要创建的区块类型。
• initialAttributes Object：传递给新创建区块的属性。
• title string：项目在插入器中显示的标题。
• icon string：项目在插入器中显示的 Dashicon。
• category string：该项目关联的区块分类。
• keywords string[]：可用于搜索以找到此项目的关键词。
• isDisabled boolean：是否应阻止用户插入此项目。
• frecency number：结合频率和最近时间的启发式值。

getLastMultiSelectedBlockClientId

返回多选集合中最后一个区块的客户端 ID，如果没有多选，则返回 null。

参数

• state Object：编辑器状态。

返回值

• ?string：多选集合中的最后一个区块客户端 ID。

getLowestCommonAncestorWithSelectedBlock

给定区块客户端 ID，返回与所选客户端 ID 的最近公共祖先。

参数

• state Object：编辑器状态。
• clientId string：用于查找公共祖先客户端 ID 的区块。

返回值

• string：公共祖先客户端 ID 或 undefined。

getMultiSelectedBlockClientIds

返回当前多选的区块客户端 ID 集合，如果没有多选，则返回空数组。

参数

• state Object：编辑器状态。

返回值

• Array：多选区块客户端 ID。

getMultiSelectedBlocks

返回当前多选的区块集合，如果没有多选，则返回空数组。

参数

• state Object：编辑器状态。

返回值

• Array：多选区块对象。

getMultiSelectedBlocksEndClientId

返回结束多选集合的区块客户端 ID，如果没有多选，则返回 null。

这不一定是所选内容中的最后一个客户端 ID。

相关

• getLastMultiSelectedBlockClientId

参数

• state Object：编辑器状态。

返回值

• ?string：结束多选的区块客户端 ID。

getMultiSelectedBlocksStartClientId

返回开始多选集合的区块客户端 ID，如果没有多选，则返回 null。

这不一定是所选内容中的第一个客户端 ID。

相关

• getFirstMultiSelectedBlockClientId

参数

• state Object：编辑器状态。

返回值

• ?string：开始多选的区块客户端 ID。

getNextBlockClientId

从给定参考起始 ID 返回下一个区块的客户端 ID。默认起始为所选区块。如果没有下一个区块，则返回 null。

参数

• state Object：编辑器状态。
• startClientId ?string：可选的区块客户端 ID，从该区块开始搜索。

返回值

• ?string：相邻区块的客户端 ID，如果不存在则返回 null。

getPatternsByBlockTypes

根据其声明的 blockTypes 和区块名称返回模式列表。模式可以使用 blockTypes 集成到工作流中，例如在 Placeholder 状态（插入期间）或区块转换中建议合适的模式。

参数

• state Object：编辑器状态。
• blockNames string|string[]：用于查找匹配模式的区块名称或区块名称数组。
• rootClientId ?string：可选的目标根客户端 ID。

返回值

• Array：根据声明的 blockTypes 和区块名称匹配的区块模式列表。

getPreviousBlockClientId

从给定参考起始 ID 返回上一个区块的客户端 ID。默认起始为所选区块。如果没有上一个区块，则返回 null。

参数

• state Object：编辑器状态。
• startClientId ?string：可选的区块客户端 ID，从该区块开始搜索。

返回值

• ?string：相邻区块的客户端 ID，如果不存在则返回 null。

getSelectedBlock

返回当前所选区块，如果没有所选区块，则返回 null。

用法

import { select } from '@wordpress/data';
import { store as blockEditorStore } from '@wordpress/block-editor';

// 设置初始活动区块客户端 ID
let activeBlockClientId = null;

const getActiveBlockData = () => {
    const activeBlock = select( blockEditorStore ).getSelectedBlock();

    if ( activeBlock && activeBlock.clientId !== activeBlockClientId ) {
        activeBlockClientId = activeBlock.clientId;

        // 获取活动区块名称和属性
        const activeBlockName = activeBlock.name;
        const activeBlockAttributes = activeBlock.attributes;

        // 记录活动区块名称和属性
        console.log( activeBlockName, activeBlockAttributes );
    }
};

// 订阅编辑器中的更改
// wp.data.subscribe(() => {
// getActiveBlockData()
// })

// 在点击时更新活动区块数据
// onclick="getActiveBlockData()"

参数

• state Object：全局应用状态。

返回值

• ?Object：所选区块。

getSelectedBlockClientId

返回当前所选区块客户端 ID，如果没有所选区块，则返回 null。

参数

• state Object：编辑器状态。

返回值

• ?string：所选区块客户端 ID。

getSelectedBlockClientIds

返回当前所选区块客户端 ID 集合（多选或单选）。

参数

• state Object：编辑器状态。

返回值

• Array：多选区块客户端 ID。

getSelectedBlockCount

返回当前在文章中被选择的区块数量。

参数

• state Object：全局应用状态。

返回值

• number：文章中被选择的区块数量。

getSelectedBlocksInitialCaretPosition

返回所选区块的初始光标位置。此位置用于在所选区块更改时正确放置光标。如果当前区块不是 RichText，初始位置设为 0 表示“聚焦区块”。

参数

• state Object：全局应用状态。

返回值

• 0|-1|null：初始位置。

getSelectedBlockStyleState

返回区块样式控件的所选样式状态。

参数

• state Object：全局应用状态。
• clientId string：区块客户端 ID。

返回值

• Object：所选区块样式状态。

getSelectionEnd

返回当前选区结束区块的客户端 ID、属性键和文本偏移量。

参数

• state Object：区块编辑器状态。

返回值

• WPBlockSelection：选区结束信息。

getSelectionStart

返回当前选区开始区块的客户端 ID、属性键和文本偏移量。

参数

• state Object：区块编辑器状态。

返回值

• WPBlockSelection：选区开始信息。

getSettings

返回编辑器设置。

参数

• state Object：编辑器状态。

返回值

• Object：编辑器设置对象。

getTemplate

返回已定义的区块模板

参数

• state boolean：

返回值

• ?Array：区块模板。

getTemplateLock

返回已定义的区块模板锁定。可选接受根区块客户端 ID 作为上下文，否则默认使用全局上下文。

参数

• state Object：编辑器状态。
• rootClientId ?string：可选的区块根客户端 ID。

返回值

• string|false：区块模板锁定

hasBlockMovingClientId

已弃用

返回是否启用区块移动模式。

hasDraggedInnerBlock

如果该区块的某个内部区块被拖动，则返回 true。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。
• deep boolean：执行深度检查。

返回值

• boolean：该区块是否有内部区块被拖动

hasInserterItems

确定插入器中是否有要显示的项目。

参数

• state Object：编辑器状态。
• rootClientId ?string：区块列表的可选根客户端 ID。

返回值

• boolean：插入器中是否有要显示的项目。

hasMultiSelection

如果已进行多选，则返回 true，否则返回 false。

参数

• state Object：编辑器状态。

返回值

• boolean：是否已进行多选。

hasSelectedBlock

如果存在单个选定区块，则返回 true，否则返回 false。

参数

• state Object：编辑器状态。

返回值

• boolean：是否选中了单个区块。

hasSelectedBlockStyleState

返回是否为区块选中了非默认样式状态。

参数

• state Object：全局应用程序状态。
• clientId string：区块客户端 ID。

返回值

• boolean：是否选中了非默认区块样式状态。

hasSelectedInnerBlock

如果该区块的某个内部区块被选中，则返回 true。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。
• deep boolean：执行深度检查。

返回值

• boolean：该区块是否有内部区块被选中

isAncestorBeingDragged

返回该区块的父级/祖先是否正在被拖动。

参数

• state Object：全局应用程序状态。
• clientId string：要检查的区块的客户端 ID。

返回值

• boolean：该区块的祖先是否正在被拖动。

isAncestorMultiSelected

如果该区块的某个祖先被多选，则返回 true，否则返回 false。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：该区块的祖先是否位于多选集合中。

isBlockBeingDragged

返回该区块是否正在被拖动。

仅当该区块被直接拖动时才返回 true；如果该区块是被拖动的父级的子级，则不返回 true。子级区块请参见 isAncestorBeingDragged。

参数

• state Object：全局应用程序状态。
• clientId string：要检查的区块的客户端 ID。

返回值

• boolean：该区块是否正在被拖动。

isBlockHighlighted

如果当前高亮的区块与区块 clientId 匹配，则返回 true。

参数

• state Object：全局应用程序状态。
• clientId string：要检查的区块。

返回值

• boolean：该区块当前是否被高亮。

isBlockInsertionPointVisible

如果区块插入点可见，则返回 true。

参数

• state Object：全局应用程序状态。

返回值

• ?boolean：插入点是否可见。

isBlockMultiSelected

如果客户端 ID 出现在区块多选中，则返回 true，否则返回 false。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：区块是否位于多选集合中。

isBlockSelected

如果与指定客户端 ID 对应的区块当前被选中且不存在多选，则返回 true，否则返回 false。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：区块是否被选中且不存在多选。

isBlockValid

返回区块是否有效。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：是否有效。

isBlockVisible

判断区块在画布上是否可见。

参数

• state Object：全局应用程序状态。
• clientId Object：区块的客户端 ID。

返回值

• boolean：如果区块可见，则为 true。

isBlockWithinSelection

如果与指定客户端 ID 对应的区块当前被选中，但不是所选区块中的最后一个，则返回 true。这里的“最后一个”是指文档中的区块顺序，而不是多选顺序，这也是不使用 state.selectionEnd 的原因。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：区块是否被选中且不是所选区块中的最后一个。

isCaretWithinFormattedText

已弃用

如果光标位于格式化文本中，则返回 true，否则返回 false。

返回值

• boolean：光标是否位于格式化文本中。

isDraggingBlocks

如果用户正在拖动区块，则返回 true，否则返回 false。

参数

• state Object：全局应用程序状态。

返回值

• boolean：用户是否正在拖动区块。

isFirstMultiSelectedBlock

如果存在多选，并且与指定客户端 ID 对应的区块是多选集合中的第一个区块，则返回 true，否则返回 false。

参数

• state Object：编辑器状态。
• clientId string：区块客户端 ID。

返回值

• boolean：区块是否为多选中的第一个区块。

isGroupable

指示所提供的区块（通过客户端 ID）是否可分组。我们需要至少有一个区块、已设置分组区块名称，并且能够移除这些区块。

参数

• state Object：全局应用程序状态。
• clientIds string[]：区块客户端 ID。如果未传递，将使用所选区块的客户端 ID。

返回值

• boolean：如果区块可分组，则为 true。

isLastBlockChangePersistent

如果最近的区块更改被视为持久更改，则返回 true，否则返回 false。持久更改是除了 onInput 之外，由 BlockEditorProvider 通过其 onChange 回调提交的更改。

参数

• state Object：区块编辑器状态。

返回值

• boolean：最近的区块更改是否为持久更改。

isMultiSelecting

是否处于多选过程中。该标志仅在正在通过鼠标移动选择多选时为 true，一旦多选完成，即为 false。

相关

• hasMultiSelection

参数

• state Object：全局应用状态。

返回值

• boolean：如果正在多选，则为 true，否则为 false。

isSelectionEnabled

返回是否启用多选的选择器。

参数

• state Object：全局应用状态。

返回值

• boolean：如果应允许多选区块，则为 true；如果多选已禁用，则为 false。

isTyping

如果用户正在输入，则返回 true，否则返回 false。

参数

• state Object：全局应用状态。

返回值

• boolean：用户是否正在输入。

isUngroupable

指示区块是否可取消分组。如果区块是带有内部区块的单个分组区块，则该区块可取消分组。如果区块具有 ungroup 转换，则它也可取消分组，而无需是默认分组区块。此外，区块只有在具有内部区块且可被移除时才能取消分组。Section 区块不可取消分组。

参数

• state Object：全局应用状态。
• clientId string：区块的客户端 ID。如果未传入，将使用所选区块的客户端 ID。

返回值

• boolean：如果该区块可取消分组，则为 true。

isValidTemplate

返回区块是否与模板匹配。

参数

• state boolean：

返回值

• ?boolean：模板是否有效。

wasBlockJustInserted

判断具有所传递 clientId 的区块是否刚刚插入。

参数

• state Object：全局应用状态。
• clientId Object：区块的客户端 ID。
• source ?string：区块的可选插入来源。

返回值

• boolean：如果该区块与从指定来源最后插入的区块匹配，则为 true。

动作

clearSelectedBlock

清除区块选择的动作。

返回值

• Object：动作对象。

duplicateBlocks

复制一组区块的动作。

参数

• clientIds string[]：
• updateSelection boolean：

enterFormattedText

已弃用

返回一个动作对象，用于发出光标已进入格式化文本的信号。

返回值

• Object：动作对象。

exitFormattedText

已弃用

返回一个动作对象，用于发出用户光标已退出格式化文本的信号。

返回值

• Object：动作对象。

flashBlock

通过有节奏地高亮显示使具有给定 clientId 的区块“闪烁”的动作。

参数

• clientId string：目标区块的客户端 ID。
• timeout number：保持高亮的持续时间（毫秒）。默认为 150 毫秒。

hideInsertionPoint

隐藏插入点的动作。

hoverBlock

已弃用

返回一个动作对象，用于发出指定客户端 ID 的区块已被悬停的信号。

insertAfterBlock

在给定区块之后插入默认区块的动作。

参数

• clientId string：

insertBeforeBlock

在给定区块之前插入默认区块的动作。

参数

• clientId string：

insertBlock

插入单个区块的动作，可选择在相对于根区块列表的特定索引处插入。

只会插入允许的区块。对于不允许的区块，或者区块列表上的 templateLock 处于激活状态时，该动作可能会静默失败。

参数

• block Object：要插入的区块对象。
• index ?number：应插入区块的索引。
• rootClientId ?string：可选，要在其上插入的区块列表的根客户端 ID。
• updateSelection ?boolean：如果为 true，将更新区块选择。如果为 false，区块选择不会改变。默认为 true。
• initialPosition 0|-1|null：初始焦点位置。将其设为 null 可防止聚焦插入的区块。
• meta ?Object：可选，要传递给动作对象的 Meta 值。

返回值

• Object：动作对象。

insertBlocks

插入一组区块的动作，可选择在相对于根区块列表的特定索引处插入。

只会插入允许的区块。对于不允许的区块，或者区块列表上的 templateLock 处于激活状态时，该动作可能会静默失败。

参数

• blocks Object[]：要插入的区块对象数组。
• index ?number：应插入区块的索引。
• rootClientId ?string：可选，要在其上插入的区块列表的根客户端 ID。
• updateSelection ?boolean：如果为 true，将更新区块选择。如果为 false，区块选择不会改变。默认为 true。
• initialPosition 0|-1|null：初始焦点位置。将其设为 null 可防止聚焦插入的区块。
• meta ?Object：可选，要传递给动作对象的 Meta 值。

返回值

• Object：动作对象。

insertDefaultBlock

向区块列表添加默认类型新区块的动作。

参数

• attributes ?Object：可选，要分配的区块属性。
• rootClientId ?string：可选，要追加到的区块列表的根客户端 ID。
• index ?number：可选，插入默认区块的索引。

mergeBlocks

合并两个区块的动作。

参数

• firstBlockClientId string：要合并的第一个区块的客户端 ID。
• secondBlockClientId string：要合并的第二个区块的客户端 ID。

moveBlocksDown

未文档化的声明。

moveBlocksToPosition

将给定区块移动到新位置的动作。

参数

• clientIds ?string：区块的客户端 ID。
• fromRootClientId ?string：根客户端 ID 来源。
• toRootClientId ?string：根客户端 ID 目标。
• index number：要将区块移动到的索引。

moveBlocksUp

未文档化的声明。

moveBlockToPosition

将给定区块移动到新位置的动作。

参数

• clientId ?string：区块的客户端 ID。
• fromRootClientId ?string：根客户端 ID 来源。
• toRootClientId ?string：根客户端 ID 目标。
• index number：要将区块移动到的索引。

multiSelect

更改区块多选的动作。

参数

• start string：多选的第一个区块。
• end string：多选的最后一个区块。
• __experimentalInitialPosition number|null：可选初始位置。传入 null 以跳过编辑器画布内的聚焦。

receiveBlocks

已弃用

返回一个动作对象，用于发出已接收区块的信号。与 resetBlocks 不同，这些区块应追加到现有已知集合中，而不是替换。

参数

• blocks Object[]：区块对象数组。

返回值

• Object：动作对象。

registerInserterMediaCategory

注册一个新的插入器媒体分类。注册后，该媒体分类将在插入器的媒体选项卡中可用。

使用以下接口：

类型定义

• InserterMediaRequest Object：插入器媒体请求的接口。

属性

• per_page number：每页获取的项目数。
• page [number]：要获取哪一页结果。默认为第一页。
• search string：用于过滤结果的搜索词。

类型定义

• InserterMediaItem Object：插入器媒体响应的接口。任何媒体资源都应将其响应映射到此接口，以便创建核心 WordPress 媒体区块（图像、视频、音频）。

属性

• title string：媒体项目的标题。
• url `string：媒体项目的源 URL。
• previewUrl [string]：要在媒体列表中显示的媒体项目预览源 URL。
• id [number]：媒体项目的 WordPress ID。
• sourceId [number|string]：来自外部来源的媒体项目的 ID。
• alt [string]：媒体项目的替代文本。
• caption [string]：媒体项目的说明。

类型定义

• InserterMediaResponse Object：分页插入器媒体响应的接口。媒体类别的 fetch 可以返回此类型而不是普通数组以启用分页；在这种情况下，媒体选项卡会为该类别渲染分页控件。

属性

• mediaItems InserterMediaItem[]：请求页面的媒体项目。
• totalItems number：所有页面的项目总数。
• totalPages number：可用总页数。

用法

wp.data.dispatch( 'core/block-editor' ).registerInserterMediaCategory( {
    name: 'openverse',
    labels: {
        name: 'Openverse',
        search_items: 'Search Openverse',
    },
    mediaType: 'image',
    async fetch( query = {} ) {
        const defaultArgs = {
            mature: false,
            excluded_source: 'flickr,inaturalist,wikimedia',
            license: 'pdm,cc0',
        };
        const finalQuery = { ...query, ...defaultArgs };
        // 有时你可能需要按照 `InserterMediaRequest` 接口映射支持的请求参数。
        // 在此示例中，`search` 查询参数名为 `q`。
        const mapFromInserterMediaRequest = {
            per_page: 'page_size',
            search: 'q',
        };
        const url = new URL( 'https://api.openverse.org/v1/images/' );
        Object.entries( finalQuery ).forEach( ( [ key, value ] ) => {
            const queryKey = mapFromInserterMediaRequest[ key ] || key;
            url.searchParams.set( queryKey, value );
        } );
        const response = await window.fetch( url, {
            headers: {
                'User-Agent': 'WordPress/inserter-media-fetch',
            },
        } );
        const jsonResponse = await response.json();
        const results = jsonResponse.results;
        return results.map( ( result ) => ( {
            ...result,
            // 如果响应结果包含你之后需要访问的 `id` 属性，应将其
            // 映射到 `InserterMediaItem` 的 `sourceId` 属性。如果你提供
            // 举报 URL 获取函数，这会很有用。
            // 此外，你应该始终清除响应结果的 `id` 值，因为
            // 它用于标识 WordPress 媒体项目。
            sourceId: result.id,
            id: undefined,
            caption: result.caption,
            previewUrl: result.thumbnail,
        } ) );
    },
    getReportUrl: ( { sourceId } ) =>
        `https://wordpress.org/openverse/image/${ sourceId }/report/`,
    isExternalResource: true,
} );

参数

• category InserterMediaCategory：要注册的插入器媒体类别。

类型定义

• InserterMediaCategory Object：插入器媒体类别的接口。

属性

• name string：媒体类别的名称，在所有媒体类别中应唯一。
• labels Object：媒体类别的标签。
• labels.name string：媒体类别的通用名称。它用于插入器媒体项目列表中。
• labels.search_items [string]：搜索项目的标签。默认值为 ‘Search Posts’ / ‘Search Pages’。
• mediaType ('image'|'audio'|'video')：媒体类别的媒体类型。
• fetch (InserterMediaRequest) => Promise<InserterMediaItem[]|InserterMediaResponse>：用于获取该类别媒体项目的函数。返回 InserterMediaResponse 而不是普通数组会使该类别启用分页。
• getReportUrl [(InserterMediaItem) => string]：如果媒体类别支持举报媒体项目，此函数应返回该媒体项目的举报 URL。它接受 InserterMediaItem 作为参数。
• isExternalResource [boolean]：如果媒体类别是外部资源，应将其设置为 true。这用于在检查该类别是否有可在媒体选项卡中显示的媒体项目时避免向外部资源发起请求。
• emptyMessage [string]：当来源没有项目且没有活动搜索时，代替通用 “No results found.” 显示的可选消息。提供该消息还会在来源为空时将其保留在选项卡列表中，因此该消息保持可访问。

removeBlock

返回一个动作对象，用于表示指定客户端 ID 的区块将被移除。

参数

• clientId string：要移除的区块的客户端 ID。
• selectPrevious boolean：如果在移除区块时应选择前一个区块，则为 true。

返回值

• Object：动作对象。

removeBlocks

生成动作对象，用于表示与指定客户端 ID 集合对应的区块将被移除。

参数

• clientIds string|string[]：要移除的区块的客户端 ID。
• selectPrevious boolean：如果在移除区块时应选择前一个区块或直接父区块（如果不存在前一个区块），则为 true。

replaceBlock

用一或多个替换区块替换单个区块的动作。

参数

• clientId (string|string[])：要替换的区块客户端 ID。
• block (Object|Object[])：替换区块（一个或多个）。

返回值

• Object：动作对象。

replaceBlocks

用一或多个替换区块替换给定区块的动作。

参数

• clientIds (string|string[])：要替换的区块客户端 ID（一个或多个）。
• blocks (Object|Object[])：替换区块（一个或多个）。
• indexToSelect number：要选择的替换区块的索引。
• initialPosition 0|-1|null：操作后所选区块中脱字符的索引。
• meta ?Object：要传递给动作对象的可选 Meta 值。

返回值

• Object：动作对象。

replaceInnerBlocks

返回一个动作对象，用于表示指定客户端 ID 的 InnerBlocks 应被替换。

参数

• rootClientId string：其 InnerBlocks 将被替换的区块的客户端 ID。
• blocks Object[]：要作为新 InnerBlocks 插入的区块对象。
• updateSelection ?boolean：如果为 true，将更新区块选择。如果为 false，区块选择不会改变。默认值为 false。
• initialPosition 0|-1|null：初始区块位置。

返回值

• Object：动作对象。

resetBlocks

将区块状态重置为指定区块数组的动作，优先于状态中作为编辑反映的任何其他内容。

参数

• blocks Array：区块数组。

resetSelection

返回一个动作对象，用于表示选择状态应重置为指定选择。

参数

• selectionStart WPBlockSelection：选择起始。
• selectionEnd WPBlockSelection：选择结束。
• initialPosition 0|-1|null：初始区块位置。

返回值

• Object：动作对象。

selectBlock

返回一个动作对象，用于表示指定客户端 ID 的区块已被选择，并可选接受一个反映其选择方向的位置值。initialPosition 为 -1 表示反向选择。

参数

• clientId string：区块客户端 ID。
• initialPosition 0|-1|null：可选初始位置。传入 -1 以反映反向选择，或传入 null 以阻止聚焦该区块。

返回值

• Object：动作对象。

selectionChange

更改用户脱字符位置的动作。

参数

• clientId string|WPSelection：所选区块的客户端 ID。
• attributeKey string：所选区块的属性键。

返回

• Object：动作对象。

selectNextBlock

生成用于发出信号的动作对象，表示应选择给定 clientId 之后的区块。

参数

• clientId string：区块客户端 ID。

selectPreviousBlock

生成用于发出信号的动作对象，表示应选择给定 clientId 之前的区块（或可选地，其自下而上的第一个父区块）。

参数

• clientId string：区块客户端 ID。
• fallbackToParent boolean：如果为 true，则在没有前一个区块时选择第一个父区块。

setBlockEditingMode

为给定区块设置区块编辑模式。

相关

• useBlockEditingMode

参数

• clientId string：区块客户端 ID，若为根容器则为 ''。
• mode BlockEditingMode：区块编辑模式。取值为 'disabled'、'contentOnly' 或 'default' 之一。

返回

• Object：动作对象。

setBlockMovingClientId

已弃用

设置区块移动客户端 ID。

返回

• Object：动作对象。

setBlockVisibility

设置给定区块在画布上是否可见的动作。

参数

• updates Record<string,boolean>：针对每个区块的 clientId，其新的可见性设置。

setHasControlledInnerBlocks

设置区块是否具有受控内部区块的动作。

参数

• clientId string：区块的 clientId。
• hasControlledInnerBlocks boolean：如果区块的内部区块受控，则为 true。

setTemplateValidity

重置模板有效性的动作。

参数

• isValid boolean：模板有效性标志。

返回

• Object：动作对象。

showInsertionPoint

显示插入点的动作。

参数

• rootClientId ?string：用于插入的区块列表的可选根客户端 ID。
• index ?number：应插入区块的索引。
• __unstableOptions ?Object：附加选项。

返回

• Object：动作对象。

属性

• __unstableWithInserter boolean：是否显示插入器按钮。
• operation WPDropOperation：应用时要执行的操作，目前为 ‘insert’ 或 ‘replace’。

startDraggingBlocks

返回一个动作对象，用于发出用户已开始拖动区块的信号。

参数

• clientIds string[]：正在拖动的客户端 ID 数组

返回

• Object：动作对象。

startMultiSelect

开始区块多选的动作。

返回

• Object：动作对象。

startTyping

返回一个动作对象，用于发出用户已开始输入的信号。

返回

• Object：动作对象。

stopDraggingBlocks

返回一个动作对象，用于发出用户已停止拖动区块的信号。

返回

• Object：动作对象。

stopMultiSelect

停止区块多选的动作。

返回

• Object：动作对象。

stopTyping

返回一个动作对象，用于发出用户已停止输入的信号。

返回

• Object：动作对象。

synchronizeTemplate

将模板与区块列表同步的动作。

返回

• Object：动作对象。

toggleBlockHighlight

切换区块高亮状态的动作。

参数

• clientId string：区块的 clientId。
• isHighlighted boolean：高亮状态。

toggleBlockMode

返回一个动作对象，用于在可视化模式和 HTML 模式之间切换区块编辑模式。

参数

• clientId string：区块客户端 ID。

返回

• Object：动作对象。

toggleSelection

启用或禁用区块选择的动作。

参数

• isSelectionEnabled [boolean]：是否应启用区块选择。

返回

• Object：动作对象。

unsetBlockEditingMode

清除给定区块的区块编辑模式。

相关

• useBlockEditingMode

参数

• clientId string：区块客户端 ID，若为根容器则为 ''。

返回

• Object：动作对象。

updateBlock

更新具有指定客户端 ID 的区块的动作。

参数

• clientId string：区块客户端 ID。
• updates Object：要合并的区块属性。

返回

• Object：动作对象。

updateBlockAttributes

更新具有指定客户端 ID 的多个区块属性的动作。

参数

• clientIds string|string[]：区块客户端 ID。
• attributes Object：要合并的区块属性。如果 options.uniqueByBlock 为 true，则应以 clientIds 作为键。
• options Object：更新选项。
• options.uniqueByBlock [boolean]：clientIds 数组中的每个区块是否具有唯一的属性集。

返回

• Object：动作对象。

updateBlockListSettings

更改给定区块嵌套设置的动作。

参数

• clientId string | SettingsByClientId：正在接收嵌套设置的区块的客户端 ID，或者按客户端 ID 分组的设置对象。
• settings Object：包含嵌套区块新设置的对象。

返回

• Object：动作对象

updateSettings

更新区块编辑器设置的动作。

参数

• settings Object：更新后的设置

返回

• Object：动作对象

validateBlocksToTemplate

区块有效性取决于区块状态（在重置时）和模板设置。作为对其分布在状态不同部分之间的折衷，这里将其实现为区块重置动作的副作用。

参数

• blocks Array：区块数组。