【CodeMirror】系列（二）官网示例（五）可撤销操作、拆分视图、斑马条纹

一、可撤销操作

默认情况下，history 历史记录扩展仅跟踪文档和选择的更改，撤销操作只会回滚这些更改，而不会影响编辑器状态的其他部分。
不过你也可以将其他的操作定义成可撤销的。如果把这些操作看作状态效果，就可以把相关功能整合进核心的历史模块。实现的方式是注册这些效果为可逆的。当历史记录检测到某个事务有这样的效果时，它会存储该效果的反转，并在撤销这个事务时应用反转效果。
举个例子：
我们来创建一个扩展，允许用户突出显示文档中的某些部分，并能够撤销这种高亮。
我们将突出显示的范围信息存储在一个状态字段中，并定义效果来添加和移除这些范围。

import {StateEffect, ChangeDesc} from "@codemirror/state"// 定义添加高亮的效果
const addHighlight = StateEffect.define<{from: number, to: number}>({map: mapRange // 定义映射函数
})// 定义移除高亮的效果
const removeHighlight = StateEffect.define<{from: number, to: number}>({map: mapRange // 同样的映射函数
})// 映射函数：根据更改调整范围
function mapRange(range: {from: number, to: number}, change: ChangeDesc) {let from = change.mapPos(range.from), to = change.mapPos(range.to)return from < to ? {from, to} : undefined
}

这些效果可以添加到事务中，并可以通过代码查看事务的效果。由于效果包含文档位置，必须定义一个映射函数，以便在某些情况下（例如，当不希望将更改加入历史时），能够正确调整，以确保撤销效果应用于正确的文档。
我们定义一个状态字段，用于保存代表高亮范围的装饰。当每次有与高亮相关的事务来时，这个字段的更新函数会应用这些效果。

import {Decoration, DecorationSet} from "@codemirror/view"
import {StateField} from "@codemirror/state"// 定义高亮样式
const highlight = Decoration.mark({attributes: {style: `background-color: rgba(255, 50, 0, 0.3)`}
})// 定义高亮范围的状态字段
const highlightedRanges = StateField.define({create() {return Decoration.none // 初始化为空},update(ranges, tr) {ranges = ranges.map(tr.changes) // 应用变更for (let e of tr.effects) {if (e.is(addHighlight))ranges = addRange(ranges, e.value) // 添加高亮范围else if (e.is(removeHighlight))ranges = cutRange(ranges, e.value) // 移除高亮范围}return ranges // 返回更新后的范围},provide: field => EditorView.decorations.from(field) // 提供装饰
})

为了确保我们管理的高亮范围不会有重叠或碎片，我们定义一些辅助方法来清除或添加范围。当需要添加新范围时，我们会将与之相邻的原有高亮合并为一个连续的范围；如果需要移除范围，只保留未被移除区域的部分。

// 移除高亮范围的函数
function cutRange(ranges: DecorationSet, r: {from: number, to: number}) {let leftover = []ranges.between(r.from, r.to, (from, to, deco) => {if (from < r.from) leftover.push(deco.range(from, r.from))if (to > r.to) leftover.push(deco.range(r.to, to))})return ranges.update({filterFrom: r.from,filterTo: r.to,filter: () => false,add: leftover})
}function addRange(ranges: DecorationSet, r: {from: number, to: number}) {ranges.between(r.from, r.to, (from, to) => {if (from < r.from) r = {from, to: r.to}if (to > r.to) r = {from: r.from, to}})return ranges.update({filterFrom: r.from,filterTo: r.to,filter: () => false,add: [highlight.range(r.from, r.to)]})
}

现在我们可以定义效果反转的逻辑。我们传给 invertedEffects 的函数会在每个事务中被调用，并返回一个效果数组，供历史记录存储和该事务的反转效果一起使用。
这个函数的作用是把添加高亮的效果转换为移除高亮的效果，反之亦然。
因为删除高亮周围的区域也会删除高亮，而我们可能希望在撤销删除操作时恢复这些高亮，所以这个函数还会遍历所有被替换的范围，并为其中任何被覆盖的高亮创建一个高亮效果。

import {invertedEffects} from "@codemirror/commands"const invertHighlight = invertedEffects.of(tr => {let found = []for (let e of tr.effects) {if (e.is(addHighlight)) found.push(removeHighlight.of(e.value)) // 如果是添加高亮的效果，添加移除高亮的效果else if (e.is(removeHighlight)) found.push(addHighlight.of(e.value)) // 如果是移除高亮的效果，添加添加高亮的效果}let ranges = tr.startState.field(highlightedRanges) // 获取当前状态中的高亮范围tr.changes.iterChangedRanges((chFrom, chTo) => { // 遍历变化的范围ranges.between(chFrom, chTo, (rFrom, rTo) => {let from = Math.max(chFrom, rFrom), to = Math.min(chTo, rTo) // 计算重叠区域if (from < to) found.push(addHighlight.of({from, to})) // 如果有重叠，添加高亮效果})})return found // 返回找到的效果
})

这两个命令将我们定义的效果应用于任何选中的范围。

import {EditorView} from "@codemirror/view"// 高亮选中的区域
function highlightSelection(view: EditorView) {view.dispatch({effects: view.state.selection.ranges.filter(r => !r.empty) // 只对非空的选中区域应用效果.map(r => addHighlight.of(r)) // 添加高亮效果})return true
}// 撤销高亮
function unhighlightSelection(view: EditorView) {let highlighted = view.state.field(highlightedRanges) // 获取当前高亮范围let effects = []for (let sel of view.state.selection.ranges) {highlighted.between(sel.from, sel.to, (rFrom, rTo) => {let from = Math.max(sel.from, rFrom), to = Math.min(sel.to, rTo) // 计算重叠区域if (from < to) effects.push(removeHighlight.of({from, to})) // 添加移除高亮的效果})}view.dispatch({effects}) // 执行效果return true
}

请注意，unhighlightSelection 只为之前高亮的、与当前选择重叠的范围创建效果。如果我们简单地对整个选中范围创建了效果，反转这些效果可能会导致一些之前没有高亮的内容被错误地添加高亮。

import {keymap} from "@codemirror/view"// 定义快捷键
const highlightKeymap = keymap.of([{key: "Mod-h", run: highlightSelection}, // 添加高亮的快捷键{key: "Shift-Mod-h", run: unhighlightSelection} // 撤销高亮的快捷键
])// 导出高亮范围的功能
export function rangeHighlighting() {return [highlightedRanges,invertHighlight,highlightKeymap]
}

如果我们把上述所有内容整合到一个扩展中，就可以让编辑器实现如下功能：
选中文本，通过快捷键 ctrl/cmd-h 可以高亮，通过 shift-ctrl/cmd-h 可以撤销高亮。

二、拆分视图

一个编辑器可以创建多个视图。但是多个视图的修改并不会自动同步。状态是不可变的值，每个视图中更新后的状态将会各自不同。
因此，为了保持两个视图内容的同步，你必须将一个视图中的更改转发到另一个视图。一个好的做法是使用重写的调度函数或更新监听器。在这个例子中，我们将使用调度函数。
为了确保只有一个撤销历史记录，我们会设置一个带有历史扩展的状态和一个没有的状态。主编辑器的状态设置如下：

// 导入必要的模块
import {EditorState} from "@codemirror/state" // 导入编辑器状态模块
import {defaultKeymap, historyKeymap, history} from "@codemirror/commands" // 导入命令和快捷键模块
import {drawSelection, keymap, lineNumbers} from "@codemirror/view" // 导入视图相关的功能模块// 创建主编辑器的初始状态
let startState = EditorState.create({doc: "The document\nis\nshared", // 设置文档内容extensions: [history(), // 启用历史记录扩展，以便支持撤销和重做drawSelection(), // 允许高亮选择lineNumbers(), // 显示行号keymap.of([...defaultKeymap, // 使用默认的快捷键...historyKeymap, // 使用与历史记录相关的快捷键])]
})

第二个编辑器的状态则不跟踪历史，它将与主编辑器共享文档内容，并将与历史相关的按键绑定到主编辑器，以执行撤销和重做操作。

// 导入撤销和重做功能
import {undo, redo} from "@codemirror/commands"// 创建第二个编辑器的初始状态，不记录历史
let otherState = EditorState.create({doc: startState.doc, // 使用主编辑器的文档内容extensions: [drawSelection(), // 允许高亮选择lineNumbers(), // 显示行号keymap.of([...defaultKeymap, // 使用默认的快捷键// 将撤销操作绑定到主编辑器{key: "Mod-z", run: () => undo(mainView)}, // 将重做操作绑定到主编辑器{key: "Mod-y", mac: "Mod-Shift-z", run: () => redo(mainView)} ])]
})  

接下来是负责在编辑器之间广播更改的代码。
为了能够区分用户的正常操作和来自其他编辑器的同步事务，我们定义一个注解来标记同步事务。每当一个导致文档变化的事务到来，而这个事务不是同步事务时，它也会被发往另一个编辑器。

// 导入视图和事务相关的模块
import {EditorView} from "@codemirror/view" // 导入编辑器视图模块
import {Transaction, Annotation} from "@codemirror/state" // 导入事务和注解模块// 定义一个注解，用于标记同步事务
let syncAnnotation = Annotation.define<boolean>()// 定义同步调度函数，用于在两个编辑器之间传递事务
function syncDispatch(tr: Transaction, view: EditorView, other: EditorView) {view.update([tr]) // 更新当前视图// 如果交易中有变化且不是同步事务if (!tr.changes.empty && !tr.annotation(syncAnnotation)) {let annotations: Annotation<any>[] = [syncAnnotation.of(true)] // 添加同步注解let userEvent = tr.annotation(Transaction.userEvent) // 获取用户事件if (userEvent) annotations.push(Transaction.userEvent.of(userEvent)) // 如果是用户事件，添加到注解中// 将变化和注解同步到另一个编辑器other.dispatch({changes: tr.changes, annotations})}
}

现在我们可以创建视图，观察它们的实际效果。

let mainView = new EditorView({state: startState,parent: document.querySelector("#editor1"),dispatch: tr => syncDispatch(tr, mainView, otherView)
})let otherView = new EditorView({state: otherState,parent: document.querySelector("#editor2"),dispatch: tr => syncDispatch(tr, otherView, mainView)
})

第一个编辑器：

第二个编辑器：

在一个编辑器中修改文本的时候，会同步修改另一个编辑器中的文本。

三、斑马条纹

这个示例定义了一个扩展，用于为每第 N 行设置背景样式，以实现斑马条纹效果。
为了使条纹的样式可以被主题覆盖，我们首先定义一个基础主题。这个主题样式化 cm-zebraStripe 类，为亮色和暗色主题设置不同的背景颜色。

// 导入编辑器视图模块
import {EditorView} from "@codemirror/view"// 定义基础主题，设置亮色和暗色主题的条纹背景
const baseTheme = EditorView.baseTheme({"&light .cm-zebraStripe": {backgroundColor: "#a4f1f188"}, // 亮色主题的背景"&dark .cm-zebraStripe": {backgroundColor: "#34474788"} // 暗色主题的背景
})

接下来，为了引入配置功能，我们允许调用者配置条纹之间的距离。为了以一种定义明确的方式存储配置的距离，即使添加了多个扩展实例，我们将其存储在一个由 facet 定义的 Facet 中。
该 Facet 可以接收任何数量的步长值（输入类型为数字），并将它们的最小值作为其值返回，默认值为 2。

// 导入 Facet 模块
import {Facet} from "@codemirror/state"// 定义步长的 Facet，组合多个值，返回最小值
const stepSize = Facet.define<number, number>({combine: values => values.length ? Math.min(...values) : 2 // 若无值则默认返回 2
})

我们将导出一个函数，该函数返回添加斑马条纹功能的扩展。请注意，扩展值可以是单个扩展（例如，由 of 方法创建的 Facet 值），也可以是扩展的数组（可能嵌套）。因此，它们可以方便地组合成更大的扩展。

// 导入扩展模块
import {Extension} from "@codemirror/state"// 导出一个函数以创建斑马条纹的扩展
export function zebraStripes(options: {step?: number} = {}): Extension {return [baseTheme, // 引入基础主题options.step == null ? [] : stepSize.of(options.step), // 可选的步长配置showStripes // 对应的样式展示插件]
}

接下来是一个辅助函数，它遍历可见行，为每第 N 行创建一个行装饰。
该插件会在每次变更时重新计算它的装饰，对于使用构建器的情况，这并不昂贵。在其他情况下，可能更希望跨更新保留装饰（在文档更改之间映射它们）。
请注意，由于 Facet 始终可以在每个状态中访问，无论它们是否已被添加到该状态中，我们可以简单读取 stepSize 的值，以获得适当的步长。当没有人配置时，其值将为 2（结果为调用其组合函数时的空数组）。

// 导入装饰模块
import {Decoration} from "@codemirror/view"
import {RangeSetBuilder} from "@codemirror/state"// 定义条纹装饰
const stripe = Decoration.line({attributes: {class: "cm-zebraStripe"} // 使用 CSS 类定义条纹
})// 函数用于创建条纹装饰
function stripeDeco(view: EditorView) {let step = view.state.facet(stepSize) // 获取步长let builder = new RangeSetBuilder<Decoration>() // 创建装饰构建器for (let {from, to} of view.visibleRanges) { // 遍历可见范围for (let pos = from; pos <= to;) {let line = view.state.doc.lineAt(pos) // 获取行if ((line.number % step) == 0) // 检查是否是第 N 行builder.add(line.from, line.from, stripe) // 为该行添加条纹装饰pos = line.to + 1 // 移动到下一行}}return builder.finish() // 返回构建完成的装饰
}

然后，showStripes 视图插件仅需声明它提供装饰（通过装饰选项），并确保在文档或视口改变时重新计算其装饰属性。

import {ViewPlugin, DecorationSet, ViewUpdate} from "@codemirror/view"const showStripes = ViewPlugin.fromClass(class {decorations: DecorationSetconstructor(view: EditorView) {this.decorations = stripeDeco(view)}update(update: ViewUpdate) {if (update.docChanged || update.viewportChanged)this.decorations = stripeDeco(update.view)}
}, {decorations: v => v.decorations
})

效果如下：