title: "区块编辑器的数据" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Data - Reference Guides - Repos

区块编辑器的数据

命名空间：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

返回在给定的起始客户端ID（startClientId）和方向性修饰符（modifier）方向上相邻的块的客户端ID。默认起始客户端ID为当前选中的块，方向为下一个块。如果没有相邻块，则返回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 会递归遍历其内部区块，直到检索完所有子区块。请注意，getBlock 不会返回内部区块控制器的子内部区块。这是因为内部区块控制器会与自身实体同步，因此不应包含在不同实体的区块中。例如，假设您调用 getBlocks( TP ) 来获取模板部件的区块。如果另一个模板部件是 TP 的子级，则嵌套模板部件的子区块将不会被返回。这样，模板区块本身被视为父级的一部分，但其子级则不是。

参数

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'：隐藏所有非内容 UI，例如工具栏中的辅助控件、区块移动器和区块设置。
'default'：允许正常编辑区块。

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

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

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

相关

useBlockEditingMode

参数

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

返回值

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

getBlockHierarchyRootClientId

给定一个区块客户端 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' 作为 blockName，则仅返回属于分组区块的父级。如果传入 [ 'core/group', 'core/cover'] 作为 blockName，则返回属于分组区块和封面区块的父级。

参数

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

返回所有匹配指定 blockName 的区块。结果包含嵌套区块。

参数

state Object: 全局应用状态。
blockName string[]: 需要返回 clientIds 的区块名称（可多个）。

返回值

Array: 名称等于 blockName 的区块的 clientIds 数组。

getBlockSelectionEnd

返回当前块选择结束位置。该值可能为空，可能表示单个块选择或多选结束位置。当选择的起始与结束位置匹配时，即为单个选择。

参数

state Object: 全局应用状态。

返回值

?string: 块选择结束位置的客户端 ID。

getBlockSelectionStart

返回当前块选择的起始位置。该值可能为空，可能表示单个块选择或多选起始位置。当选择的起始与结束位置匹配时，即为单个选择。

参数

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: 要创建的块的类型。
title string: 项目的标题，即其在插入器中显示的名称。
icon string: 项目的 Dashicon 图标，即其在插入器中显示的图标。
isDisabled boolean: 是否应阻止用户插入此项目。
frecency number: 结合频率和最近使用时间的启发式值。

getClientIdsOfDescendants

返回一个数组，包含给定块的所有后代块的 clientId。返回的 id 首先按给定 id 的顺序排序，然后按它们在编辑器中出现的顺序排序。

参数

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

返回值

Array: 后代的客户端 ID。

getClientIdsWithDescendants

返回一个数组，包含顶级区块及其任意深度（针对嵌套区块）的所有后代区块的 clientId。返回的 ID 顺序与它们在编辑器中出现的顺序一致。

参数

state Object: 全局应用状态。

返回值

Array: 顶级区块及其后代区块的 ID 列表。

getDirectInsertBlock

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

参数

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

返回值

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

类型定义

WPDirectInsertBlock Object

属性

name string: 区块的类型。
attributes ?Object: 传递给新创建区块的属性。
attributesToCopy ?Array<string>: 插入时要从相邻区块复制的属性。

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 集成到工作流中，例如在占位符状态（插入期间）或区块转换中建议合适的模式。

参数

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

Array: 基于声明的 blockTypes 和区块名称匹配的区块模式列表。

getPreviousBlockClientId

返回给定起始参考 ID 的前一个区块的客户端 ID。默认起始点为当前选中的区块。若无前一个区块则返回 null。

参数

state Object: 编辑器状态。
startClientId ?string: 可选的起始搜索区块的客户端 ID。

返回值

?string: 相邻区块的客户端 ID，若不存在则返回 null。

getSelectedBlock

Returns the currently selected block, or null if there is no selected block.

Usage

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

// Set initial active block client ID
let activeBlockClientId = null;

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

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

        // Get active block name and attributes
        const activeBlockName = activeBlock.name;
        const activeBlockAttributes = activeBlock.attributes;

        // Log active block name and attributes
        console.log( activeBlockName, activeBlockAttributes );
    }
};

// Subscribe to changes in the editor
// wp.data.subscribe(() => {
// getActiveBlockData()
// })

// Update active block data on click
// onclick="getActiveBlockData()"

Parameters

state Object: Global application state.

Returns

?Object: Selected block.

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: 初始位置。

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: 是否选中了单个区块。

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

是否处于多选过程中。此标志仅在通过鼠标移动进行多选时保持为真，一旦多选操作完成即变为假。

相关项

hasMultiSelection

参数

state Object: 全局应用状态。

返回值

boolean: 若正在多选则为真，否则为假。

isSelectionEnabled

选择器，用于返回是否启用了多选功能。

参数

state Object: 全局应用程序状态。

返回值

boolean: 如果可以多选区块则为 true，如果多选功能被禁用则为 false。

isTyping

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

参数

state Object: 全局应用状态。

返回值

boolean: 用户是否正在输入。

isUngroupable

指示一个区块是否可解组。如果一个区块是包含内部区块的单一分组区块，则该区块可解组。如果一个区块具有 ungroup 转换，则它也可解组，无需满足是默认分组区块的要求。此外，一个区块只有在具有内部区块且可被移除时才能被解组。分区区块不可解组。

参数

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

用于插入单个块的操作，可选择在根块列表的特定索引处插入。

仅允许插入已授权的块。对于未授权的块或块列表上存在模板锁的情况，此操作可能会静默失败。

参数

block Object：要插入的块对象。
index ?number：块应插入的索引位置。
rootClientId ?string：可选，要插入块的块列表的根客户端 ID。
updateSelection ?boolean：如果为 true，将更新块选择状态；如果为 false，块选择状态保持不变。默认为 true。
initialPosition 0|-1|null：初始焦点位置。设置为 null 可防止聚焦到插入的块。
meta ?Object：可选，传递给操作对象的元数据值。

返回值

Object：操作对象。

insertBlocks

用于插入块数组的操作，可选择在根块列表的特定索引处插入。

仅允许的块会被插入。对于不被允许的块，或块列表上存在模板锁时，此操作可能会静默失败。

参数

blocks Object[]: 要插入的块对象数组。
index ?number: 块应插入的索引位置。
rootClientId ?string: 可选的目标块列表的根客户端 ID。
updateSelection ?boolean: 若为 true，将更新块选择状态。若为 false，块选择状态保持不变。默认为 true。
initialPosition 0|-1|null: 初始焦点位置。设为 null 可防止聚焦到插入的块。
meta ?Object: 可选的要传递给操作对象的元数据值。

返回值

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

Registers a new inserter media category. Once registered, the media category is available in the inserter's media tab.

The following interfaces are used:

Type Definition

InserterMediaRequest Object: Interface for inserter media requests.

Properties

per_page number: How many items to fetch per page.
search string: The search term to use for filtering the results.

Type Definition

InserterMediaItem Object: Interface for inserter media responses. Any media resource should map their response to this interface, in order to create the core WordPress media blocks (image, video, audio).

Properties

title string: The title of the media item.
url `string: The source url of the media item.
previewUrl [string]: The preview source url of the media item to display in the media list.
id [number]: The WordPress id of the media item.
sourceId [number|string]: The id of the media item from external source.
alt [string]: The alt text of the media item.
caption [string]: The caption of the media item.

Usage

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 };
        // Sometimes you might need to map the supported request params according to `InserterMediaRequest`.
        // interface. In this example the `search` query param is named `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,
            // If your response result includes an `id` prop that you want to access later, it should
            // be mapped to `InserterMediaItem`'s `sourceId` prop. This can be useful if you provide
            // a report URL getter.
            // Additionally you should always clear the `id` value of your response results because
            // it is used to identify WordPress media items.
            sourceId: result.id,
            id: undefined,
            caption: result.caption,
            previewUrl: result.thumbnail,
        } ) );
    },
    getReportUrl: ( { sourceId } ) =>
        `https://wordpress.org/openverse/image/${ sourceId }/report/`,
    isExternalResource: true,
} );

Parameters

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

类型定义

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

属性

name string：媒体类别的名称，在所有媒体类别中应保持唯一。
labels Object：媒体类别的标签。
labels.name string：媒体类别的通用名称。它用于插入器媒体项目列表中。
labels.search_items [string]：搜索项目的标签。默认为‘搜索文章’/‘搜索页面’。
mediaType ('image'|'audio'|'video')：媒体类别的媒体类型。
fetch (InserterMediaRequest) => Promise<InserterMediaItem[]>：用于获取该类别媒体项目的函数。
getReportUrl [(InserterMediaItem) => string]：如果媒体类别支持报告媒体项目，此函数应返回该媒体项目的报告 URL。它接受 InserterMediaItem 作为参数。
isExternalResource [boolean]：如果媒体类别是外部资源，应将其设置为 true。这用于避免在用户

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: 可选，传递给操作对象的元数据值。

返回值

Object: 操作对象。

replaceInnerBlocks

返回一个用于发出信号的动作对象，表示应替换指定客户端 ID 的内部区块。

参数

rootClientId string: 其内部区块将被替换的区块的客户端 ID。
blocks Object[]: 作为新内部区块插入的区块对象数组。
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 的区块，并可选择接受反映其选择方向性的位置值。初始位置为 -1 表示反向选择。

参数

clientId string: 区块客户端 ID。
initialPosition 0|-1|null: 可选的初始位置。传入 -1 表示反向选择，或传入 null 以防止聚焦该区块。

返回值

Object: 动作对象。

selectionChange

用于更改用户光标位置的操作。

参数

clientId string|WPSelection: 所选区块的客户端 ID。
attributeKey string: 所选区块的属性键。
startOffset number: 起始偏移量。
endOffset number: 结束偏移量。

返回值

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: 区块的客户端 ID。
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: 块的客户端 ID。
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]: 客户端 ID 数组中的每个区块是否具有唯一的属性集。

返回值

Object: 操作对象。

updateBlockListSettings

用于更改指定区块嵌套设置的操作。

参数

clientId string | SettingsByClientId: 要获取嵌套设置的区块客户端 ID，或按客户端 ID 分组的设置对象。
settings Object: 包含嵌套区块新设置的对象。

返回值

Object: 操作对象

updateSettings

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

参数

settings Object: 更新后的设置

返回值

Object: 操作对象

validateBlocksToTemplate

区块有效性取决于区块状态（在重置时）和模板设置。作为对其分散在不同状态部分的一种折中方案，它在此处被实现为区块重置操作的一个副作用。

参数

blocks Array: 区块数组。