Day 29. slate × Transforms × Selection ＆ Text

上一篇我们统整了 NodeTransforms 里各个 methods 的用法以及参数介绍，传送门在此～

这一篇同样会以 reference 的形式统整 SelectionTransforms 以及 TextTransforms 的功用以及传入参数的用途。

SelectionTransforms

`collapse`

用途：收合编辑器 selection
参数：
- editor: Editor
- options: CollapseOptions
options ：
```
interface CollapseOptions {
	edge?: 'anchor' | 'focus' | 'start' | 'end'
}
```
- edge
  
  决定 selection 要往哪一个 Point 收合：
  - 'anchor'
    
    往 selection 的 anchor point 收合
  - 'focus'
    
    往 selection 的 focus point 收合
  - 'start'
    
    会搭配 Range.edges 以及 Range.isBackward method 判断 selection 是否为『反向的』并得出真正的起始、结束位置
    
    并往相对起始的 point 收合
  - 'end'
    
    会搭配 Range.edges 以及 Range.isBackward method 判断 selection 是否为『反向的』并得出真正的起始、结束位置
    
    并往相对结束的 point 收合

`deselect`

用途：取消设置编辑器的 selection value
参数：
- editor: Editor

里头的程序码很基本，就是直接呼叫 'set_selection' Operation

/**
 * Unset the selection.
 */

deselect(editor: Editor): void {
  const { selection } = editor

  if (selection) {
    editor.apply({
      type: 'set_selection',
      properties: selection,
      newProperties: null,
    })
  }
},

`move`

用途：向前或向後移动 selection 里头的 points 。
参数：
- editor: Editor
- options: MoveOptions
options ：
```
interface MoveOptions {
	distance?: number
  unit?: 'offset' | 'character' | 'word' | 'line'
  reverse?: boolean
  edge?: 'anchor' | 'focus' | 'start' | 'end'
}
```
- distance
  
  搭配 unit （单位）决定一次要移动的实际距离
- unit
  
  移动的单位，分为 'offset' 、 'character' 、 'word' 、 'line' 。关於不同的单位实作的细节被集中在 Editor.positions 里，包含它的演算法也都被作者 comment 在 method 里。因为太过细节了这边就不详细解说，再请有兴趣的读者自行上前查看。
- reverse
  
  决定 points 移动的方向：
  - reverse: true ：向前移动
  - reverse: false ：向後移动
- edge
  
  决定要移动的 selection point ，分为：
  - 'anchor'
    
    只移动 anchor point
  - 'focus'
    
    只移动 focus point
  - 'start'
    
    会搭配 Range.isBackward method 判断 selection 是否为『反向的』，将相对起始的 point ( 'anchor' | 'focus' ) assign 给 edge
  - 'end'
    
    会搭配 Range.isBackward method 判断 selection 是否为『反向的』，将相对结束的 point ( 'anchor' | 'focus' ) assign 给 edge
  edge 的预设值为 null ，这会同时移动 anchor 与 focus point

`select`

用途：重新设定编辑器的 selection value
参数：
- editor: Editor
- target: Location

这里头的程序码也很基本：

包含确保的 target 为 Range type
```
target = Editor.range(editor, target)
```

更新 selection 属性

const { selection } = editor

if (selection) {
  Transforms.setSelection(editor, target)
  return
}

抛出例外状况

if (!Range.isRange(target)) {
  throw new Error(
    `When setting the selection and the current selection is \`null\` you must provide at least an \`anchor\` and \`focus\`, but you passed: ${JSON.stringify(
      target
    )}`
  )
}

执行 Operation

editor.apply({
  type: 'set_selection',
  properties: selection,
  newProperties: target,
})

`setPoint`

用途：对编辑器 selection 的其中一个 Point 设定新的 props 属性
参数：
- editor: Editor
- props: Partial<Point>
- options: SetPointOptions
options ：
```
interface SetPointOptions {
	edge?: 'anchor' | 'focus' | 'start' | 'end'
}
```
- edge
  
  决定要将 props 取得的属性设定於 selection 的哪一个 Point
  - 'anchor'
    
    将 props 设定於 anchor point 上
  - 'focus'
    
    将 props 设定於 focus point 上
  - 'start'
    
    会搭配 Range.edges 以及 Range.isBackward method 判断 selection 是否为『反向的』并得出真正的起始、结束位置
    
    并将 props 设定於相对起始的 point 上
  - 'end'
    
    会搭配 Range.edges 以及 Range.isBackward method 判断 selection 是否为『反向的』并得出真正的起始、结束位置。
    
    并将 props 设定於相对结束的 point 上。

`setSelection`

用途：设定新的 props 属性在编辑器的 selection 上
参数：
- editor: Editor
- props: Partial<Range>

除了设定 custom 属性之外，它也同时确保不会将 selection 里的 anchor 或 focus point 设为 null

for (const k in props) {
  if (
    (k === 'anchor' &&
      props.anchor != null &&
      !Point.equals(props.anchor, selection.anchor)) ||
    (k === 'focus' &&
      props.focus != null &&
      !Point.equals(props.focus, selection.focus)) ||
    (k !== 'anchor' && k !== 'focus' && props[k] !== selection[k])
  ) {
    oldProps[k] = selection[k]
    newProps[k] = props[k]
  }
}

TextTransforms

`delete`

用途：移除编辑器内的文字内容
参数：
- editor: Editor
- options: DeleteOptions
options ：
```
interface DeleteOptions {
	at?: Location
  distance?: number
  unit?: 'character' | 'word' | 'line' | 'block'
  reverse?: boolean
  hanging?: boolean
  voids?: boolean
}
```
- at
  
  欲删除的文字内容於编辑器里的位置，分为三种删除情形：
  - at 传入一组 Path → 将整个节点删除
  - at 传入一组 Range → 将 Range 集合的文字内容删除
  - at 传入一个 Point → 搭配 distance 与 unit 决定要从该 Point 向前删除多少文字内容
- distance
  
  搭配 unit （单位）决定一次要移动的实际距离
- unit
  
  移动的单位，分为 'offset' 、 'character' 、 'word' 、 'line' 。关於不同的单位实作的细节被集中在 Editor.positions 里，包含它的演算法也都被作者 comment 在 method 里。因为太过细节了这边就不详细解说，再请有兴趣的读者自行上前查看。
- reverse
  
  如果传入的 at 为 Point 的话， reverse 会决定节点的删除方向
  - reverse: true ：向前删除
  - reverse: false ：向後删除
- hanging
  
  这个 value 会决定 Range 是否要另外修正为 unhanging type 。
  
  hanging 在 Slate 里头的意思代表『这段 Range 涵盖到了不存在的节点』。
  
  我们假设目前的 Slate Document 如下：
```
[{text: 'one '}, {text: 'two', bold: true}, {text: ' three'}]
```
  这时使用者看到的显示方式应该如下：
  
  one two three
  
  假设使用者选取了 "two" ，此时的 selection 会有几种 anchor 与 focus points 的可能性出现
```
// 1 -- no hanging
{
  anchor: { path: [1], offset: 0 },
  focus: { path: [1], offset: 3 }
}

// 2 -- anchor hanging
{
  anchor: { path: [0], offset: 4 },
  focus: { path: [1], offset: 3 }
}

// 3 -- focus hanging
{
  anchor: { path: [1], offset: 0 },
  focus: { path: [2], offset: 0 }
}

// 4 -- both hanging
{
  anchor: { path: [0], offset: 4 },
  focus: { path: [2], offset: 0 }
}
```
  当我们传入 hanging: false 时， Slate 就会将这组 Range 传入 Editor.unhangRange method 里确保 Range 维持在第一种情形。
- voids
  
  决定在这个 Transform method 有呼叫到的所有操作行为中，是否要略过或避开 void nodes 的出现。

这个 method 也有处理跨节点相关的情境，笔者这边暂且不多做介绍，未来有机会再追加补充。

`insertFragment`

用途：插入一组 Fragment 进指定的 at Location 里
参数：
- editor: Editor
- fragment: Node[]
- options: InsertFragmentOptions
options ：
```
interface InsertFragmentOptions {
	at?: Location
  hanging?: boolean
  voids?: boolean
}
```
- at
  
  要插入 Fragment nodes 的位置，分为三种插入情形：
  - at 传入一组 Path → 将 Fragments 插入进节点的开头位置
  - at 传入一组 Range → 将 Range 集合的文字内容移除後插入 Fragments
  - at 传入一个 Point → 直接将 Fragments 插入进该 Point 之後
- hanging
  
  如果传入的 at 为 Range type ，则这个 value 会决定 Range 是否要另外修正为 unhanging type 。
  
  详细的解释请参照上方的 DeleteOptions
- voids
  
  决定在这个 Transform method 有呼叫到的所有操作行为中，是否要略过或避开 void nodes 的出现。

`insertText`

用途：插入一段文字字串进编辑器里
参数：
- editor: Editor
- text: string
- options: InsertTextOptions
options ：
```
interface InsertTextoptions {
	at?: Location
  voids?: boolean
}
```
- at
  
  欲将文字插入於编辑器中的位置，分为三种输入情形：
  - at 传入一组 Path → 将整个节点的文字内容修改为新输入的内容
  - at 传入一组 Range → 将 Range 集合的文字内容修改为新输入的内容
  - at 传入一个 Point → 直接将新输入的内容插入进该 Point 之後
- void
  
  一组布林值，决定文字插入的节点所属的 branch 的上层祖先节点能否有 void node 存在。