Selection 模块包

Lexical 提供了一个 @lexical/selection 模块包，其中有一些关于选区的实用方法。

参考

lexical-selection - Github
@lexical/selection - documentation

注意

其中有一些方法的名称以 $ 符号开头，它们大部分是用于修改编辑器状态 EditorState 的，一般只能在 editor.update(callbackFn) 的回调函数 callbackFn 中实用

选区相关

$selectAll(selection) 将给定的范围选区 selection 进行扩展（通过调整选区的 anchor 锚定一端和 focus 移动焦点一端），全选编辑器的所有内容
$moveCaretSelection(selection, isHoldingShift, isBackward, granularity) 根据给定的参数调整/修改给定的范围选区 selection（可以用于移动或扩展一个「逻辑」单位 logical unit 选区范围）
它所接受的参数
- selection 参数：需要调整的范围选区
- isHoldingShift 参数：一个布尔值，表示当前是否按下 Shift 键（如果是则对选区进行扩展，否则对选区进行移动）
- isBackward 参数：一个布尔值，表示选区的 focus 可移动的一端是否在 anchor 锚定一端之前（如果为 true 则调整选区需要反向调整，以保证在 focus 一端发生移动）
- granularity 参数：可以是 "character" | "word" | "lineboundary" 这三个值之一，以表示调整的颗粒度/单位（按照 "character" 字符、"word" 单词还是 "lineboundary" 一行作为一个「逻辑」单位）
提示
如果选区的移动是按照 character 字符作为单位，也可以使用 $moveCharacter(selection, isHoldingShift, isBackward 该方法其实是对以上方法的封装，针对当 granularity 参数设置为 character 时的一个别名/简化方法
$shouldOverrideDefaultCharacterSelection(selection, isBackward) 返回一个布尔值，以表示是否需要改变选取的默认行为（默认的选取行为是按照字符 character 来选取 ❓ ）
参数 isBackward 是一个布尔值，表示选区的 focus 可移动的一端是否在 anchor 锚定一端之前
基于下一个节点的类型而定，如果下一个节点类型是块级的 ElementNode 元素节点或 DecoratorNode 装饰节点，则返回 true
提示
一般用于配合 DecoratorNode 节点使用，例如在富文本编辑器中，通过为 KEY_ARROW_LEFT_COMMAND 和 KEY_ARROW_RIGHT_COMMAND 指令设置响应函数，「劫持」/自定义这些按键的行为，当选区/光标的下一个节点是装饰节点时，不采用默认行为，而设置其他行为以提供用户更符合直觉的操作
createDOMRange(editor, anchorNode, _anchorOffset, focusNode, _focusOffset) 基于给定节点 anchorNode 和 focusNode，以及偏移量 _anchorOffset 和 _focusOffset，创建一个 DOM 原生的 Range 选区范围
createRectsFromDOMRange(editor, range) 基于 DOM 原生的选区范围 range 创建一个 DOMRect，便于编辑器在屏幕中定位选区/光标的位置
DOMRect
DOMRect 描述页面上的一个矩形的大小和位置，例如使用方法 Range.getBoundingClientRect() 所返回的 DOMRect 对象描述了选区范围所对应的矩形。

节点相关

$cloneWithProperties(node) 基于给定的节点 node 创建一个拷贝，它不仅具有相同的属性，而且还会设置好相同的父节点、前后兄弟节点，但是具有不同的 key 唯一标识符
$isAtNodeEnd(point) 返回一个布尔值，以判断给定的选区端点 point 是否位于某个节点的末尾
$isParentElementRTL(selection) 返回一个布尔值，以表示包裹给定的范围选区 selection 的节点（父节点，基于选区的 anchor 锚定「不动」的一端获取的父节点）的文本书写方式是否为 RTL 从右往左
$setBlocksType(selection, createElement) 将选区 selection 中的元素节点（而且是 block 块级元素类型）替换 replace 为给定的节点类型。参数 crateElement 是一个函数，它会返回一个元素节点（或其子类）
$sliceSelectedTextNodeContent(selection, textNode) 对给定的文本节点 textNode 的内容进行 slice 「裁剪」，只保留该文本节点被选区 selection 选中的部分内容。返回依然是该文本节点（但是其内容可能会被删除了部分）
$wrapNodes(selection, createElement, wrappingElement?) 将选取 selection 中的节点用 ElementNode 元素节点进行包裹，并插入 append 到给定的目标节点 wrappingElement 中
- selection 参数：一个选区，其中的节点需要进行包裹
- crateElement 参数：一个函数，该函数返回一个 ElementNode 元素节点（或子类），作为容器（用于包裹选区中的节点）
- wrappingElement（可选）参数：一个 ElementNode 元素节点，作为定位节点（经过包裹的节点会插入到该节点内）
trimTextContentFromAnchor(editor, anchor, delCount) 从当地选区的 anchor 锚定点开始，向前删除特定数量 delCount 字符
如果删除的字符量大于锚点所在的节点，则会继续向前删除（邻近节点或父节点的）内容。如果是文本节点且内容全被删除，则该文本节点也会被移除；如果是祖先节点，则保留 2 个空格的缩进 ❓

样式相关

$addNodeStyle(node) 从给定的文本节点 node 中提取出 CSS 样式（字符串形式），并解析为对象形式，暂存到一个映射里 ❓ 进行标准化，以及配合 $patchStyleText(selection, path) 使用 ❓
$getSelectionStyleValueForProperty(selection, styleProperty, defaultValue?) 在选区 selection 中寻找给定的 CSS 样式属性 styleProperty 的属性值（字符串）。
有多种情况
- 如果选区有「预设」该 CSS 样式的属性，则优先返回其值
- 如果选区没有「预设」该 CSS 样式的属性，则分析选区中所有的 TextNode 文本节点，寻找这些节点针对 CSS 样式属性 styleProperty 所设置的值。只有当应这些文本节点针对 CSS 样式属性都设置了相同的值，才返回其属性值，否则返回 ''
- 最后一个（可选）参数 defaultValue 是用于设置默认的样式值
$patchStyleText(selection, patch) 将给定的 CSS 样式 patch 应用到选区中的 TextNode 文本节点
参数 patch 是一个对象，其中属性名称是各种 CSS 样式的属性，属性值是相应的 CSS 样式值
该方法可能会对文本节点执行节点分割 splitting 操作，以便只针对选中的部分字符设置 CSS 样式
getStyleObjectFromCSS(css) 解析传入的 css 行内样式（字符串形式），返回一个对象（其中属性名称是各种 CSS 样式的属性，属性值是相应的 CSS 样式值）