diffUtility

比较两个文档并返回它们之间变化的列表。

支持的格式

Diff 实用工具可用于比较整个文档或其部分内容。

要比较整个文档，可以以 Tiptap JSON 格式 或 ProseMirror Node 提供它们。

要比较文档的部分内容，可以将其作为 Tiptap JSON 片段（Tiptap JSON 节点列表）或 ProseMirror Fragment 提供。

参数 (DiffUtilityOptions)

• schema (Schema)：编辑器使用的 ProseMirror schema。可从编辑器实例获取：editor.schema
• docA (Node | Fragment | JSONContent | JSONContent[])：原始文档。可以是 ProseMirror Node/Fragment 或 Tiptap JSON
• docB (Node | Fragment | JSONContent | JSONContent[])：修改后的文档。可以是 ProseMirror Node/Fragment 或 Tiptap JSON
• simplifyChanges? (boolean)：是否简化变更，使得如果同一单词中有多个变更，它们会合并为一个变更。当模式为 'block' 时不适用。默认值：true
• ignoreAttributes? (string[])：要忽略的属性。默认值：['id', 'data-thread-id']
• ignoreMarks? (string[])：要忽略的标记。默认值：['inlineThread']
• changeMergeDistance? (number | null)：被视为显著的未更改范围的最小长度。比该值更短的未更改范围将合并到相邻的更改中，合并为一个整体更改。设置为 null 或 undefined 可使用自动计算的默认值。当模式为 'block' 时不适用。默认值：10
• groupInlineChanges? (number)：控制在 'smart' 模式下，何时将内联编辑合并为一个块级更改。使用 1（默认）仅在所有内联内容都改变时合并，0 总是合并，2 从不合并。
• mode? ('smart' | 'inline' | 'block')：比较使用的 diff 模式。
  • 'smart'（默认）在块级和内联级别之间平衡输出，便于阅读审阅建议。
  • 'inline' 进行字符级 diff，识别文本中具体的变更。
  • 'block' 进行块级 diff，将每个顶级节点视为单个单元。块级模式下，simplifyChanges 和 changeMergeDistance 选项被忽略。

在下面的在线演示中，点击“显示 diff 选项”按钮，查看每个选项如何影响 diff 结果：

返回值 (Change[])

返回一个变更列表。每个 Change 项目包含：

• rangeA (Range)：原始文档中发生变化的范围
• rangeB (Range)：修改后文档中发生变化的范围

示例

import { diffUtility } from '@tiptap-pro/ai-toolkit'

// 计算两个文档之间的变更（默认使用 'smart' 模式）
const changes = diffUtility({
  schema: editor.schema,
  docA,
  docB,
})

// 使用块级 diff
const blockChanges = diffUtility({
  schema: editor.schema,
  docA,
  docB,
  mode: 'block',
})

// 使用字符级（内联） diff
const inlineChanges = diffUtility({
  schema: editor.schema,
  docA,
  docB,
  mode: 'inline',
})

实时比较文档

实时比较两个文档，并在编辑器中显示 diff。

有关比较文档的逐步指南，请参阅比较文档指南。

startComparingDocuments

开始与另一个文档的实时比较。差异以建议的形式显示在内联 diff 视图中，编辑器中同时显示旧内容和新内容。

参数 (StartComparingDocumentsOptions)

• otherDoc? (Node)：要进行比较的文档。它是一个 ProseMirror Node 对象。如果省略，默认使用当前文档的快照
• displayOptions? (DisplayOptions)：控制差异如何以建议的形式呈现。查看可用选项。
• debounceTimeout? (number)：重新计算 diff 之前等待的毫秒数。较低的值会让应用看起来更响应，但在大型文档中可能会导致性能问题。默认值：500
• diffUtilityOptions? (ExternalDiffUtilityOptions)：使用 diff 实用工具比较文档时的选项。查看可用选项。

返回值

void

示例

// 开始与另一个文档比较变更
toolkit.startComparingDocuments({
  otherDoc,
})

stopComparingDocuments

停止实时比较并清除所有建议，diff 视图将不再可见。

返回值

void

示例

// 停止比较并清除装饰
toolkit.stopComparingDocuments()

接受和拒绝变更

在比较文档时，变更以建议的形式显示。要接受或拒绝单个变更或一次性处理所有变更，请使用以下建议方法：

• acceptSuggestion：接受特定变更
• rejectSuggestion：拒绝特定变更
• acceptAllSuggestions：接受所有变更
• rejectAllSuggestions：拒绝所有变更

使用示例见比较文档指南。