---
title: "Diff 实用工具"
description: "以编程方式计算两个文档之间的变化。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/diff-utility"
---

# Diff 实用工具

以编程方式计算两个文档之间的变化。

## `diffUtility`

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

### 支持的格式

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

要比较整个文档，可以以 [Tiptap JSON 格式](https://tiptap.zhcndoc.com/editor/core-concepts/introduction.md#content) 或 [ProseMirror Node](https://prosemirror.net/docs/ref/#model.Node) 提供它们。

要比较文档的部分内容，可以将其作为 Tiptap JSON 片段（Tiptap JSON 节点列表）或 [ProseMirror Fragment](https://prosemirror.net/docs/ref/#model.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 结果：

> **Interactive demo:** [React](https://deploy-preview-405--tiptap-pro.netlify.app/src/Extensions/AiToolkitCompareDocuments/React/)

### 返回值 (`Change[]`)

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

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

### 示例

```ts
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。

> **适用于非 AI 用例:**
>
> 此功能无需 AI 即可工作。它可以比较任何两个文档，无论其是否由 AI 生成。一个常见用例是比较 AI 编辑前后的文档。详见[审阅变更指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/agents/review-changes-as-summary.md)。

有关比较文档的逐步指南，请参阅[比较文档指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/advanced-guides/compare-documents.md)。

## `startComparingDocuments`

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

### 参数 (`StartComparingDocumentsOptions`)

- `otherDoc?` (`Node`)：要进行比较的文档。它是一个 [ProseMirror Node 对象](https://prosemirror.net/docs/ref/#model.Node)。如果省略，默认使用当前文档的快照
- `displayOptions?` (`DisplayOptions`)：控制差异如何以建议的形式呈现。[查看可用选项](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#the-suggestion-object)。
- `debounceTimeout?` (`number`)：重新计算 diff 之前等待的毫秒数。较低的值会让应用看起来更响应，但在大型文档中可能会导致性能问题。默认值：`500`
- `diffUtilityOptions?` ([`ExternalDiffUtilityOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/diff-utility.md#parameters-diffutilityoptions))：使用 diff 实用工具比较文档时的选项。[查看可用选项](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/diff-utility.md#parameters-diffutilityoptions)。

### 返回值

`void`

### 示例

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

## `stopComparingDocuments`

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

### 返回值

`void`

### 示例

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

## 接受和拒绝变更

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

- [`acceptSuggestion`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#acceptsuggestion)：接受特定变更
- [`rejectSuggestion`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#rejectsuggestion)：拒绝特定变更
- [`acceptAllSuggestions`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#acceptallsuggestions)：接受所有变更
- [`rejectAllSuggestions`](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#rejectallsuggestions)：拒绝所有变更

使用示例见[比较文档指南](https://tiptap.zhcndoc.com/content-ai/capabilities/ai-toolkit/advanced-guides/compare-documents.md)。