gutenbergdocs/docs/reference-guides/data/data-core-block-editor.md

### updateBlockListSettings

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

**参数**

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

**返回值**

-   `Object`: 操作对象

### updateSettings

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

**参数**

-   _settings_ `Object`: 更新后的设置

**返回值**

-   `Object`: 操作对象

### validateBlocksToTemplate

区块有效性是区块状态（在重置时）与模板设置的函数。作为对其在不同状态部分中位置的折中方案，此处将其实现为区块重置操作的副作用。

**参数**

-   _blocks_ `Array`: 区块数组

<!-- END TOKEN(Autogenerated actions|../../../packages/block-editor/src/store/actions.js) -->

### 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（选择下一个区块）

生成操作对象，用于发出信号指示应选择给定客户端ID之后的下一个区块。

**参数**

-   _clientId_ `string`：区块的客户端ID。

### selectPreviousBlock（选择上一个区块）

生成操作对象，用于发出信号指示应选择给定客户端ID之前的上一个区块（或可选择从下到上的第一个父级）。

**参数**

-   _clientId_ `string`：区块的客户端ID。
-   _fallbackToParent_ `boolean`：如果为 true，在没有上一个区块时选择第一个父级。

### getLowestCommonAncestorWithSelectedBlock

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

**参数**

-   _state_ `Object`：编辑器状态。
-   _clientId_ `string`：用于查找公共祖先客户端ID的起始区块。

**返回值**

-   `string`：公共祖先客户端ID或未定义值

### getMultiSelectedBlockClientIds

返回当前多选区块的客户端ID集合，若无多选则返回空数组。

**参数**

-   _state_ `Object`：编辑器状态。

**返回值**

-   `Array`：多选区块的客户端ID集合。

### getMultiSelectedBlocks

返回当前多选区块的对象集合，若无多选则返回空数组。

**参数**

-   _state_ `Object`：编辑器状态。

**返回值**

-   `Array`：多选区块对象集合。

### getMultiSelectedBlocksEndClientId

返回多选集合的结束区块客户端ID，若无多选则返回null。

注意：该ID不一定是选区中的最后一个客户端ID。

**关联函数**

-   getLastMultiSelectedBlockClientId

**参数**

-   _state_ `Object`：编辑器状态。

**返回值**

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

### getMultiSelectedBlocksStartClientId

返回多选集合的起始区块客户端ID，若无多选则返回null。

注意：该ID不一定是选区中的第一个客户端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

返回当前选定的区块对象，若无选定区块则返回null。

**使用示例**

```js
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`：选定的区块对象。

### 是否处于多选状态

指示是否正处于多选过程中。该标志仅在通过鼠标移动进行多选时为真，多选完成后将变为假。

**相关项**

-   hasMultiSelection

**参数**

-   _state_ `对象`: 全局应用状态。

**返回值**

-   `布尔值`: 若处于多选状态返回真，否则返回假。

### 是否启用多选

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

**参数**

-   _state_ `对象`: 全局应用状态。

**返回值**

-   `布尔值`: 若允许多选块则返回真，若禁用多选则返回假。

### 是否正在输入

若用户正在输入则返回真，否则返回假。

**参数**

-   _state_ `对象`: 全局应用状态。

**返回值**

-   `布尔值`: 用户是否正在输入。

### 是否可解组

指示块是否可解组。若块为包含内部块的单一分组块，则该块可解组。若块具有“解组”转换，则即使不是默认分组块也可解组。此外，仅当块包含内部块且可被移除时才能解组。

**参数**

-   _state_ `对象`: 全局应用状态。
-   _clientId_ `字符串`: 块的客户端ID。若未传递，则使用所选块的客户端ID。

**返回值**

-   `布尔值`: 若块可解组则返回真。

### 是否为有效模板

返回块是否与模板匹配。

**参数**

-   _state_ `布尔值`:

**返回值**

-   `?布尔值`: 模板是否有效。

### 块是否刚被插入

判断指定clientId的块是否刚被插入。

**参数**

-   _state_ `对象`: 全局应用状态。
-   _clientId_ `对象`: 块的客户端ID。
-   _source_ `?字符串`: 块的可选插入来源。

**返回值**

-   `布尔值`: 若该块与指定来源最后插入的块匹配则返回真。

<!-- END TOKEN(Autogenerated selectors|../../../packages/block-editor/src/store/selectors.js) -->

## 操作

<!-- START TOKEN(Autogenerated actions|../../../packages/block-editor/src/store/actions.js) -->

### 清除选中块

清除块选择的操作。

**返回值**

-   `对象`: 操作对象。

### 复制块

复制块列表的操作。

**参数**

-   _clientIds_ `字符串[]`:
-   _updateSelection_ `布尔值`:

### 进入格式化文本

> **已弃用**

返回用于指示光标已进入格式化文本的操作对象。

**返回值**

-   `对象`: 操作对象。

### 退出格式化文本

> **已弃用**

返回用于指示用户光标已退出格式化文本的操作对象。

**返回值**

-   `对象`: 操作对象。

### 闪烁块

通过律动高亮方式“闪烁”指定`clientId`块的操作。

**参数**

-   _clientId_ `字符串`: 目标块客户端ID。
-   _timeout_ `数字`: 高亮持续时长（毫秒）。默认为150毫秒。

### 隐藏插入点

隐藏插入点的操作。

### 悬停块

> **已弃用**

返回用于指示指定客户端ID的块已被悬停的操作对象。

### 在块后插入

在指定块后插入默认块的操作。

**参数**

-   _clientId_ `字符串`:

### 在块前插入

在指定块前插入默认块的操作。

**参数**

-   _clientId_ `字符串`:

### 插入块

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

仅允许插入已授权的块。若块未获授权或块列表上存在模板锁定，该操作可能会静默失败。

**参数**

-   _block_ `对象`: 要插入的块对象。
-   _index_ `?数字`: 块应插入的索引位置。
-   _rootClientId_ `?字符串`: 要插入的块列表的可选根客户端ID。
-   _updateSelection_ `?布尔值`: 若为真则更新块选择状态。若为假则保持原选择状态。默认为真。
-   _meta_ `?对象`: 要传递给操作对象的可选元数据值。

**返回值**

-   `对象`: 操作对象。

### setBlockEditingMode

设置指定区块的编辑模式。

_相关_

-   useBlockEditingMode

_参数_

-   _clientId_ `string`: 区块客户端ID，根容器使用 `''`
-   _mode_ `BlockEditingMode`: 区块编辑模式。可选值：`'disabled'`、`'contentOnly'` 或 `'default'`

_返回值_

-   `Object`: 操作对象

### setBlockMovingClientId

> **已弃用**

设置被移动区块的客户端ID。

_返回值_

-   `Object`: 操作对象

### setBlockVisibility

设置指定区块在画布上的可见性。

_参数_

-   _updates_ `Record<string,boolean>`: 包含各区块客户端ID及其新可见性设置的键值对

### 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

更新多个指定区块的属性。

_参数_

-   _clientIds_ `string|string[]`: 区块客户端ID（单个或数组）
-   _attributes_ `Object`: 待合并的区块属性。若 `options.uniqueByBlock` 为true，应按clientIds建立键值映射
-   _options_ `Object`: 更新选项
-   _options.uniqueByBlock_ `[boolean]`: clientIds数组中每个区块是否具有独立属性集

_返回值_

-   `Object`: 操作对象

```markdown
### getSelectedBlockClientId

返回当前选中区块的客户端ID，若无选中区块则返回null。

_参数_

-   _state_ `Object`: 编辑器状态。

_返回值_

-   `?string`: 选中区块的客户端ID。

### getSelectedBlockClientIds

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

_参数_

-   _state_ `Object`: 编辑器状态。

_返回值_

-   `Array`: 多选区块的客户端ID数组。

### getSelectedBlockCount

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

_参数_

-   _state_ `Object`: 全局应用状态。

_返回值_

-   `number`: 文章中选中的区块数量。

### getSelectedBlocksInitialCaretPosition

返回选中区块的初始光标位置。该位置用于在选中区块变更时正确定位光标。若当前区块非富文本区块，初始位置设为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`: 该区块的祖先级是否处于多选集合中。
```

### getBlockParentsByBlockName（根据区块名称获取父级区块列表）

给定一个区块客户端ID和区块名称，返回其所有父级区块从顶至底的列表，并按指定名称进行筛选。例如，若传入 'core/group' 作为区块名称，则仅返回属于群组区块的父级。若传入 `[ 'core/group', 'core/cover']` 作为区块名称，则同时返回群组区块和封面区块的父级。

**参数**
-   _state_ `Object`：编辑器状态。
-   _clientId_ `string`：需要查找根级客户端ID的区块。
-   _blockName_ `string|string[]`：用于筛选的区块名称（可多选）。
-   _ascending_ `boolean`：排序方式。设为 true 时按从底到顶排列，false 时按从顶到底排列。

**返回值**
-   `Array`：父级区块的客户端ID集合。

### getBlockRootClientId（获取区块根级客户端ID）

根据区块客户端ID，返回该区块嵌套结构的根级区块。顶层区块返回空字符串，不存在的区块返回 null。

**参数**
-   _state_ `Object`：编辑器状态。
-   _clientId_ `string`：需要查找根级客户端ID的区块。

**返回值**
-   `?string`：根级客户端ID（若存在）。

### getBlocks（获取全部区块）

以数组形式返回当前编辑文章中的所有区块对象，排列顺序与文章中的显示顺序一致。注意：此操作将排除嵌套内部区块控制器中的子区块。

**参数**
-   _state_ `Object`：编辑器状态。
-   _rootClientId_ `?string`：可选参数，指定区块列表的根级客户端ID。

**返回值**
-   `Object[]`：文章区块集合。

### getBlocksByClientId（根据客户端ID获取区块）

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

**参数**
-   _state_ `Object`：编辑器状态。
-   _clientIds_ `string[]`：需要获取的区块客户端ID集合。

**返回值**
-   `WPBlock[]`：区块对象数组。

### getBlocksByName（根据名称获取区块）

返回所有匹配指定区块名称的区块，搜索结果包含嵌套区块。

**参数**
-   _state_ `Object`：全局应用状态。
-   _blockName_ `string[]`：需要获取的区块名称集合。

**返回值**
-   `Array`：符合名称条件的区块客户端ID数组。

### getBlockSelectionEnd（获取区块选区终点）

返回当前区块选区的终点。该值可能为 null，可能表示单选区块终点或多选区块终点。当选区起点与终点一致时为单选状态。

**参数**
-   _state_ `Object`：全局应用状态。

**返回值**
-   `?string`：区块选区终点的客户端ID。

### getBlockSelectionStart（获取区块选区起点）

返回当前区块选区的起点。该值可能为 null，可能表示单选区块起点或多选区块起点。当选区起点与终点一致时为单选状态。

**参数**
-   _state_ `Object`：全局应用状态。

**返回值**
-   `?string`：区块选区起点的客户端ID。

### getBlockTransformItems（获取区块转换项列表）

确定可用区块转换列表中显示的条目。

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

“frecency”属性是结合了区块使用频率和近期使用情况的启发式指标（<https://zh.wikipedia.org/wiki/使用频率与近因度>）。

返回的条目按“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（获取后代区块的客户端ID）

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

**参数**

-   _state_ `Object`：全局应用程序状态。
-   _rootIds_ `string|string[]`：需要返回后代区块的客户端ID（单个或多个）。

**返回值**

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

### getClientIdsWithDescendants（获取包含后代的客户端ID）

返回一个数组，包含顶级区块及其任意深度的后代区块（适用于嵌套区块）的客户端ID。返回的ID顺序与它们在编辑器中出现的顺序一致。

**参数**

-   _state_ `Object`：全局应用程序状态。

**返回值**

-   `Array`：顶级区块及后代区块的ID。

### getDirectInsertBlock（获取直接插入的区块）

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

**参数**

-   _state_ `Object`：编辑器状态。
-   _rootClientId_ `?string`：区块列表的可选根客户端ID。

**返回值**

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

**类型定义**

-   _WPDirectInsertBlock_ `Object`

**属性**

-   _name_ `string`：区块的类型。
-   _attributes_ `?Object`：传递给新创建区块的属性。
-   _attributesToCopy_ `?Array<string>`：插入时从相邻区块复制的属性。

### getDraggedBlockClientIds（获取被拖动区块的客户端ID）

返回当前被直接拖动的区块的客户端ID。

此结果不包括被拖动父区块的子区块。

**参数**

-   _state_ `Object`：全局应用程序状态。

**返回值**

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

### getFirstMultiSelectedBlockClientId（获取多选区块集合中的首个客户端ID）

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

**参数**

-   _state_ `Object`：编辑器状态。

**返回值**

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

### getGlobalBlockCount（获取全局区块数量）

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

**参数**

-   _state_ `Object`：全局应用程序状态。
-   _blockName_ `?string`：可选的区块名称，如果指定，则仅统计该类型的区块。

**返回值**

-   `number`：文章中的区块数量，或与指定区块名称相同的区块数量。

### getHoveredBlockClientId（获取悬停区块的客户端ID）

> **已弃用**

返回当前悬停的区块。

### getInserterItems（获取插入器项目）

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

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

“frecency”属性是一种结合了区块使用频率和最近使用时间的启发式算法（<https://en.wikipedia.org/wiki/Frecency>）。

项目按其“效用”和“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）

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

**参数**

-   _state_ `Object`：编辑器状态。

**返回值**

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

### isBlockBeingDragged（是否正在拖拽区块）

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

仅当区块被直接拖拽时返回 true，若区块作为被拖拽父级的子级则不会返回 true。关于子区块请参阅 `isAncestorBeingDragged`。

**参数**

-   _state_ `Object`：全局应用状态。
-   _clientId_ `string`：需检查区块的客户端 ID。

**返回值**

-   `boolean`：区块是否正在被拖拽。

### isBlockHighlighted（区块是否高亮）

若当前高亮区块与指定区块客户端 ID 匹配则返回 true。

**参数**

-   _state_ `Object`：全局应用状态。
-   _clientId_ `string`：需检查的区块。

**返回值**

-   `boolean`：区块当前是否处于高亮状态。

### isBlockInsertionPointVisible（区块插入点是否可见）

返回区块插入点是否可见。

**参数**

-   _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。持久化变更指通过 BlockEditorProvider 的 `onChange` 回调（及 `onInput`）提交的变更。

**参数**

-   _state_ `Object`：区块编辑器状态。

**返回值**

-   `boolean`：最近一次区块变更是否具有持久性。

### 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`: 要查找父级层级的区块。
-   _ascending_ `boolean`: 按从底到顶(true)或从上到下(false)排序结果。

**返回值**

-   `Array`: 父级区块的客户端ID数组。

# 区块编辑器的数据

命名空间：`core/block-editor`

## 选择器

<!-- START TOKEN(Autogenerated selectors|../../../packages/block-editor/src/store/selectors.js) -->

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

_参数_

-   _state_ `Object`: 编辑器状态
-   _clientId_ `string`: 区块客户端 ID

_返回值_

-   `Object`: 解析后的区块对象

```markdown
### 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

注册新的插入器媒体分类。注册后，该媒体分类将在插入器的媒体标签页中可用。

使用的接口如下：

_类型定义_

-   _InserterMediaRequest_ `Object`: 插入器媒体请求接口

_属性_

-   _per_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]`: 媒体项说明文字

_使用示例_

```js
wp.data.dispatch( 'core/block-editor' ).registerInserterMediaCategory( {
	name: 'openverse',
	labels: {
		name: 'Openverse',
		search_items: '搜索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]`: 搜索项目标签，默认为‘搜索文章’/‘搜索页面’
-   _mediaType_ `('image'|'audio'|'video')`: 媒体分类的媒体类型
-   _fetch_ `(InserterMediaRequest) => Promise<InserterMediaItem[]>`: 获取该分类媒体项目的函数
-   _getReportUrl_ `[(InserterMediaItem) => string]`: 如果媒体分类支持举报媒体项，此函数应返回媒体项的举报URL，接收`InserterMediaItem`作为参数
-   _isExternalResource_ `[boolean]`: 如果媒体分类属于外部资源，应设为true。这用于避免在用户操作时向外部资源发起请求
```