ProseMirror History 模块
prosemirror-history 模块为编辑器提供 undo 撤销和 redo 重做的功能,其中需要恢复的历史记录是可选择的(即不单单能回滚到上一个操作),还可以选择性地保留某些修改(这对于协同编辑很重要)。
该模块导出了一些属性和方法与历史记录功能相关。
创建插件
使用该模块所提供的方法 history(config?) 根据给定的配置对象 config 创建一个插件,将插件注册到编辑器上就可以实现历史记录功能
提示
(可选)参数 config 是一个对象(默认值为空对象 {})以配置编辑器历史记录功能的相关行为:
- (可选)属性
depth:一个数值(默认值为100)表示历史栈的最大长度,超过时会抛弃最早的操作记录 - (可选)属性
newGroupDelay:一个数值(默认值为500),表示两次编辑操作被视为同一历史步骤(即同一历史事件分组 group)的最大时间间隔(以毫秒为单位)。
当连续进行编辑操作(应用一系列事务 transactions)时,并且操作的时间差小于newGroupDelay设置的值时,这些操作会被视为同一个历史事件组,它们在历史栈中作为一个记录,即 undo 时会一次性撤回这一系列事务所导致的修改注意
如果两次编辑操作并非发生在接近的文档位置(它们之间有未被编辑的内容),即使这两次操作的时间间隔小于
newGroupDelay属性所设定的值,这两次操作仍然会被拆分为不同的历史事件组即除了时间间隔之外,操作所发生在文档中的位置也是影响操作是否被视为同一组。这个机制确保了具有实际意义的操作能够正确分组,以提供更直观的撤销和重做行为
预设指令
该模块导出了一些与历史记录功能相关的 command 指令,可以实现以编程式/命令式地调用历史记录相关功能:
undo属性:表示一个 command 指令,调用该指令会撤销历史栈的(如果存在)最后一个操作redo属性:表示一个 command 指令,调用该指令会重做历史栈的(如果存在)最后一个操作undoNoScroll属性:表示一个 command 指令,调用该指令会会撤销历史栈的(如果存在)最后一个操作,但并不会触发页面滚动(其目的是将选区移入视图中)redoNoScroll属性:表示一个 command 指令,调用该指令会重做历史栈的(如果存在)最后一个操作,但并不会触发页面滚动(其目的是将选区移入视图中)
历史记录信息
该模块导出了一些方法,调用它们可以获取与历史记录相关的信息:
undoDepth(state)方法:返回一个数字,表示(在给定的state编辑器状态中所保存的)历史栈中可撤回 undo 的最大操作数redoDepth(state)方法:返回一个数字,表示(在给定的state编辑器状态中所保存的)历史栈中可重做 redo 的最大操作数
其他
另外还可以使用方法 closeHistory(tr) 为给定的 tr 事务添加一个元信息,以表示后续的 step 操作步骤不能再添加到该事务上(而应该新建另外的事务来承载),并返回该事务
注意
该方法并不是停止编辑器的历史记录功能,而是用于立即手动结束当前的历史分组 group,则后续的操作就需要分到新的历史分组 group 里(不论后续的操作与当前操作的时间间隔多短)
一般通过历史插件的配置对象属性 newGroupDelay 来控制何时自动开始一个新的历史事件组,但有时希望强制开始一个新的历史组,而不依赖于时间间隔或编辑操作的位置。在这种情况下,就可以使用 closeHistory 方法
例如当用户进行了一个重要的编辑操作后,无论用户接下来的编辑操作多快开始,可能希望新的操作不和前一个重要操作归为一组,那么就可以在重要操作之后调用该方法来确保这个操作独立成组