ProseMirror History 模块

prosemirror

ProseMirror History 模块

prosemirror-history 模块为编辑器提供 undo 撤销和 redo 重做的功能,其中需要恢复的历史记录是可选择的(即不单单能回滚到上一个操作),还可以选择性地保留某些修改(这对于协同编辑很重要)。

该模块导出了一些属性和方法与历史记录功能相关。

创建插件

使用该模块所提供的方法 history(config?) 根据给定的配置对象 config 创建一个插件,将插件注册到编辑器上就可以实现历史记录功能

提示

该插件会追踪撤销和重做的操作栈 stacks,这样就与 undo 指令redo 指令相结合以实现 undo 和 redo 操作

如果不想将特定的事务 transaction 添加到历史栈上,可以为该事务设置元信息,键名为 addToHistory 其值为 false,以阻止该事务在 undo 时被撤销

(可选)参数 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 方法

例如当用户进行了一个重要的编辑操作后,无论用户接下来的编辑操作多快开始,可能希望新的操作不和前一个重要操作归为一组,那么就可以在重要操作之后调用该方法来确保这个操作独立成组


Copyright © 2025 Ben

Theme BlogiNote

Icons from Icônes