2551654928/gutenbergdocs

Fork 0

unknown 28ad1b3935 docs

2025-10-22 01:40:18 +08:00

46 KiB

Raw Blame History

updateBlockListSettings

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

参数

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

返回值

Object: 操作对象

updateSettings

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

参数

settings Object: 更新后的设置

返回值

Object: 操作对象

validateBlocksToTemplate

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

参数

blocks Array: 区块数组

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。

使用示例

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 ?字符串: 块的可选插入来源。

返回值

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

操作

清除选中块

清除块选择的操作。

返回值

对象: 操作对象。

复制块

复制块列表的操作。

参数

clientIds 字符串[]:
updateSelection 布尔值:

进入格式化文本

已弃用

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

返回值

对象: 操作对象。

退出格式化文本

已弃用

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

返回值

对象: 操作对象。

闪烁块

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

参数

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

隐藏插入点

隐藏插入点的操作。

悬停块

已弃用

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

在块后插入

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

参数

clientId 字符串:

在块前插入

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

参数

clientId 字符串:

插入块

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

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

参数

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

返回值

对象: 操作对象。

setBlockEditingMode

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

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

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

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: 操作对象

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

选择器

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: 解析后的区块对象

### 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。这用于避免在用户操作时向外部资源发起请求

46 KiB Raw Blame History Unescape Escape

updateBlockListSettings

updateSettings

validateBlocksToTemplate

removeBlock（移除区块）

removeBlocks（移除多个区块）

replaceBlock（替换区块）

replaceBlocks（替换多个区块）

replaceInnerBlocks（替换内部区块）

resetBlocks（重置区块）

resetSelection（重置选择）

selectBlock（选择区块）

selectionChange（选择变更）

selectNextBlock（选择下一个区块）

selectPreviousBlock（选择上一个区块）

getLowestCommonAncestorWithSelectedBlock

getMultiSelectedBlockClientIds

getMultiSelectedBlocks

getMultiSelectedBlocksEndClientId

getMultiSelectedBlocksStartClientId

getNextBlockClientId

getPatternsByBlockTypes

getPreviousBlockClientId

getSelectedBlock

是否处于多选状态

是否启用多选

是否正在输入

是否可解组

是否为有效模板

块是否刚被插入

操作

清除选中块

复制块

进入格式化文本

退出格式化文本

闪烁块

隐藏插入点

悬停块

在块后插入

在块前插入

插入块

setBlockEditingMode

setBlockMovingClientId

setBlockVisibility

setHasControlledInnerBlocks

setTemplateValidity

showInsertionPoint

startDraggingBlocks

startMultiSelect

startTyping

stopDraggingBlocks

stopMultiSelect

stopTyping

synchronizeTemplate

toggleBlockHighlight

toggleBlockMode

toggleSelection

unsetBlockEditingMode

updateBlock

updateBlockAttributes

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

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

getBlocks（获取全部区块）

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

getBlocksByName（根据名称获取区块）

getBlockSelectionEnd（获取区块选区终点）

getBlockSelectionStart（获取区块选区起点）

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

getClientIdsOfDescendants（获取后代区块的客户端ID）

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

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

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

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

getGlobalBlockCount（获取全局区块数量）

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

getInserterItems（获取插入器项目）

getLastMultiSelectedBlockClientId（获取多选区块集合中的最后一个客户端ID）

isBlockBeingDragged（是否正在拖拽区块）

isBlockHighlighted（区块是否高亮）

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

46 KiB

Raw Blame History