集成文档历史

Available in Start plan

文档历史记录您的内容的每个更改，因此您可以撤消错误、审核编辑或从任何点分支出新的草稿。

本页面将引导您通过历史扩展的安装、配置和常见任务。

公共演示

编辑器内容在所有演示访问者之间共享。

访问 private 注册表

版本历史扩展已在 Tiptap 的私有 npm 注册表中发布。通过遵循私有注册表指南集成该扩展。如果您已经验证了您的 Tiptap 帐户，可以直接转到 #安装。

安装


npm install @tiptap-pro/extension-collaboration-history @hocuspocus/transformer

@hocuspocus/transformer 将 Yjs 更新转换为 Tiptap JSON，并将 yjs 列为对等依赖项。如果缺少它，请运行 npm install yjs。

设置

设置	类型	默认值
provider	`TiptapCollabProvider`	`null`
onUpdate	`function`	`() => {}`

自动版本控制

自动版本控制功能会在固定时间间隔内自动创建文档的新版本。这确保您拥有全面的变更历史，而无需手动干预。

您可以使用 toggleVersioning 命令来切换此功能（默认：禁用）。

当您启用自动版本控制时，Tiptap 会在固定时间间隔内创建新版本（默认为 30 秒，仅在文档更改时）。这可能会创建许多版本，因此您可能想要增加间隔。要自定义间隔，可以执行以下操作：

// 设置自动版本之间的间隔（秒）
const ydoc = provider.configuration.document
ydoc.getMap<number>('__tiptapcollab__config').set('intervalSeconds', 900)

恢复到某个版本

当您恢复到以前的版本时：

如果有未保存的更改，Tiptap 会自动创建一个版本以保留这些更改。
Tiptap 会在历史记录的顶部创建一个新版本，其中包含您选择的版本的内容。
所有用户可以从此新版本继续工作。

请注意，恢复仅影响 ydoc 中的 default 片段。当您恢复 Tiptap 内容时，评论不会改变（除非您在 TiptapCollabProvider 中指定不同的 field）。

您可以集成比较快照扩展以突出版本之间的差异，以确保您选择正确的版本进行恢复。

存储

键	类型	描述
currentVersion	`number`	当前版本。
lastSaved	`Date`	最后保存的时间戳
latestVersion	`number`	最新版本。
provider	`TiptapCollabProvider`	协作提供者实例
status	`string`	提供者的状态 - 可以是 `connecting`、`connected` 或 `disconnected`
synced	`boolean`	版本历史是否与服务器同步
versioningEnabled	`boolean`	是否启用版本控制
versions	`array<Version>`	存储在历史中的版本数组。

命令

命令	描述
saveVersion	创建一个具有给定标题的新版本
toggleVersioning	切换此文档的自动版本控制
revertToVersion	恢复到特定版本，可以使用可选标题创建一个新的恢复版本

示例

基本设置

const provider = new TiptapCollabProvider({
  // ...
})

const editor = new Editor({
  // ...
  extensions: [
    // ...
    CollabHistory.configure({
      provider,
    }),
  ],
})

存储版本更新

在此示例中，我们检索版本更新的数据并将其保存到变量中

let currentVersion = 0
let latestVersion = 0
let autoversioningEnabled = false
let versions = []

const provider = new TiptapCollabProvider({
  // ...
})

const editor = new Editor({
  // ...
  extensions: [
    // ...
    CollabHistory.configure({
      provider,
      onUpdate(payload) {
        currentVersion = payload.currentVersion
        latestVersion = payload.version
        versions = payload.versions
        autoversioningEnabled = payload.autoVersioning
      },
    }),
  ],
})

直接从存储访问版本数据

const provider = new TiptapCollabProvider({
  // ...
})

const editor = new Editor({
  // ...
  extensions: [
    // ...
    CollabHistory.configure({
      provider,
    }),
  ],
})

const latestVersion = editor.storage.collabHistory.latestVersion
const currentVersion = editor.storage.collabHistory.currentVersion
const versions = editor.storage.collabHistory.versions
const autoversioningEnabled = editor.storage.collabHistory.versioningEnabled

手动创建新版本

editor.commands.saveVersion('我的新自定义版本')

切换文档上的自动版本控制

editor.commands.toggleVersioning()

根据版本 ID 恢复

editor.commands.revertToVersion(4)

根据版本 ID 使用自定义名称恢复

在此示例中，编辑器命令帮助您返回到版本 4。当您使用此命令时，它将带您回到版本 4 的状态，并且还将此旧版本保存为名为“恢复到版本”的新版本。这样，您可以从版本 4 继续工作，但它现在作为最新版本保存。

editor.commands.revertToVersion(4, '恢复到版本')

恢复、命名并备份

在此示例中，当您恢复到文档的版本 4 时，编辑器会自动创建两个新版本。第一个新版本记录并保存文档在恢复之前的状态，作为备份。第二个新版本将文档恢复到版本 4，允许您从这里继续作为新的起点。

editor.commands.revertToVersion(4, '恢复到版本', '恢复之前的未版本更改')

为您的编辑器实现版本预览

上述示例直接修改文档，并且没有提供本地的版本预览。因此，您必须为此需求创建自己的前端解决方案。您可以利用 TiptapCloudProvider 的无状态消息系统请求服务器上的特定版本。

首先，将侦听器附加到提供者：

// 导入 getPreviewContentFromVersionPayload 辅助函数（请参阅下面的详细信息）
import { watchPreviewContent } from '@tiptap-pro/extension-collaboration-history'

// 配置提供者
const provider = new TiptapCollabProvider({ ... })

// 使用 watchPreviewContent 工具函数监视提供者上的内容更改
const unbindWatchContent = watchPreviewContent(provider, content => {
  // 设置编辑器的内容
  editor.commands.setContent(content)
})

如果您想解除绑定观察者，可以像这样调用返回的 unbindWatchContent 函数：

const unbindWatchContent = watchPreviewContent(provider, (content) => {
  // 设置编辑器的内容
  editor.commands.setContent(content)
})

// 解除观察
unbindWatchContent()

按照此设置，您可以像这样触发 version.preview 请求：

// 定义一个函数，向提供者发送 version.preview 请求
const requestVersion = (version) => {
  provider.sendStateless(
    JSON.stringify({
      action: 'version.preview',
      // 在此处包含您的版本号
      version,
    }),
  )
}

// 触发请求
requestVersion(1)

// 然后您可以将此函数链接到按钮点击或其他 UI 元素以触发请求。

要超越预览并可视化比较不同版本，比较快照扩展提供了一种简单的方法，允许您在编辑器中查看两个版本之间的更改。

实用函数

getPreviewContentFromVersionPayload

该函数将协作提供者的有效负载转换为 Tiptap JSON 内容。

参数	描述
payload	版本预览事件的 Hocuspocus 有效负载
field	您想要解析的字段。默认值：`default`

const myContent = getPreviewContentFromVersionPayload(payload, 'default')

watchPreviewContent

该函数在您的提供者上设置了一个观察者，该观察者监视必要的事件以响应版本内容更改。它还返回一个新函数，您可以使用该函数解除对这些事件的观察。

参数	描述
provider	协作提供者
callback	被调用的回调函数，参数是 Tiptap JSON 内容
field	被监视的字段 - 默认为 `default`

const unwatchContent = watchPreviewContent(provider, editor.commands.setContent, 'default')

// 解除观察版本预览内容
unwatchContent()

可能的提供者有效负载

以下是可以从提供者发送或接收的有效负载列表：

外发

`document.revert`

请求将文档恢复到给定版本，并可选设置标题。

provider.sendStateless(
  JSON.stringify({
    action: 'document.revert',
    version: 1,
    currentVersionName: '恢复到版本 1 之前',
    newVersionName: '恢复到版本 1',
  }),
)

`version.create`

创建一个具有可选标题的新版本。

this.options.provider.sendStateless(
  JSON.stringify({ action: 'version.create', name: '我的自定义版本' }),
)

内收

`saved`

此无状态消息可用于检索最后保存的时间戳。

provider.on('stateless', (data) => {
  const payload = JSON.parse(data.payload)

  if (payload.action === 'saved') {
    const lastSaved = new Date()
  }
})

`version.created`

此无状态消息包含有关新创建版本的信息。

provider.on('stateless', (data) => {
  const payload = JSON.parse(data.payload)

  if (payload.action === 'version.created') {
    const latestVersion = payload.version
    const currentVersion = payload.version
  }
})

`document.reverted`

此无状态消息包含有关文档恢复的信息。

provider.on('stateless', (data) => {
  const payload = JSON.parse(data.payload)

  if (payload.action === 'document.reverted') {
    const currentVersion = payload.version
  }
})