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