---
title: "变更追踪扩展"
description: "在您的 Tiptap 编辑器中启用变更追踪和建议模式，以支持协作编辑和文档审阅。"
canonical_url: "https://tiptap.zhcndoc.com/editor/extensions/functionality/tracked-changes"
---

# 变更追踪扩展

在您的 Tiptap 编辑器中启用变更追踪和建议模式，以支持协作编辑和文档审阅。

Tracked Changes 扩展启用了协作编辑工作流的建议模式。启用后，所有编辑都会以提议的形式出现，可以被接受或拒绝，类似于文字处理软件中的变更追踪。

> **更多详情:**
>
> 有关如何集成、安装和配置 Tiptap Tracked Changes 扩展的更详细信息，请访问我们的 [功能页面](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md)。

> **实验性:**
>
> 此扩展正在积极开发中。API 在未来版本中可能会发生变化。所有低于 1.0.0 的版本预期不稳定，使用时请自行承担风险。

> **Interactive demo:** [TrackedChanges](https://embed-pro.tiptap.dev/preview/Experiments/TrackedChanges)

## 安装

```bash
npm install @tiptap-pro/extension-tracked-changes
```

## 基本设置

```js
import { Editor } from '@tiptap/core'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'

const editor = new Editor({
  extensions: [
    TrackedChanges.configure({
      enabled: true,
      userId: 'user-123',
      userMetadata: { name: 'John Doe' },
    }),
  ],
})
```

## 编程式建议

除了交互式审查工作流外，该扩展还提供了用于直接从应用程序逻辑创建追踪建议的命令。当你需要插入、删除或替换内容作为建议，而无需为每次编辑器交互都开启追踪变更模式时，请使用这些命令。你还可以为编程式建议附加一个 `reason`，它会随创建事件一起发出，以供下游工作流使用。插入和替换命令接受完整的 Tiptap `Content`，因此它们可以处理诸如图片之类的 JSON 节点，而不仅仅是纯文本。追踪标记命令既支持简单的格式标记（如 `bold`），也支持带属性的标记（如 `link` 或 `highlight`）。

如果你还使用了 [TrailingNode](https://tiptap.zhcndoc.com/editor/extensions/functionality/trailing-node.md) 扩展，`addTrackedInsertion()` 和 `addTrackedReplacement()` 可以设置 `skipTrailingNode: true` 以将该事务元数据转发到发出的追踪变更事务上。

```js
editor.commands.addTrackedInsertion({
  from: 7,
  content: 'big ',
  reason: 'Applied assistant suggestion',
})

editor.commands.addTrackedDeletion({
  from: 7,
  to: 12,
  reason: 'Removed deprecated sentence',
})

editor.commands.addTrackedReplacement({
  from: 7,
  to: 12,
  content: 'earth',
  reason: 'Standardized terminology',
  skipTrailingNode: true,
})

editor.commands.addTrackedMark({
  from: 7,
  to: 12,
  markName: 'bold',
  reason: 'Emphasized approved terminology',
})

editor.commands.toggleTrackedMark({
  from: 7,
  to: 12,
  markName: 'link',
  markAttrs: {
    href: 'https://tiptap.dev',
    target: '_blank',
  },
  reason: 'Added canonical reference',
})
```

```js
editor.commands.addTrackedInsertion({
  from: 7,
  content: {
    type: 'image',
    attrs: {
      src: '/example.png',
      alt: 'Example image',
    },
  },
  reason: 'Inserted approved image asset',
})
```

完整 API 请见 [命令参考](https://tiptap.zhcndoc.com/tracked-changes/api-reference/commands.md)。

## 下一步

- [安装与配置](https://tiptap.zhcndoc.com/tracked-changes/getting-started/install.md) — 完整设置参考
- [基本用法](https://tiptap.zhcndoc.com/tracked-changes/usage/basic-usage.md) — 启用追踪，接受和拒绝建议
- [高级用法](https://tiptap.zhcndoc.com/tracked-changes/usage/advanced-usage.md) — 分组、协作、评论集成
- [API 参考](https://tiptap.zhcndoc.com/tracked-changes/api-reference/commands.md) — 命令、事件、工具和类型