集成快照

文档历史记录记录您内容的每一次更改，以便您能够撤回错误、审核编辑或从任何时刻创建新草稿。

本页将向您介绍历史扩展的安装、配置和常见任务。

公共演示

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

访问专用注册表

版本历史扩展发布在 Tiptap 的私有 npm 注册表中。按私有注册表指南操作集成该扩展。如果您已经对您的 Tiptap 账户进行了身份验证，您可以直接跳转至 #安装。

安装


npm install @tiptap-pro/extension-snapshot @hocuspocus/transformer

注意： @hocuspocus/transformer 包用于将 Y.js 的二进制数据转换为 Tiptap JSON。同时也需要安装 Y.js 以支持协作。如果尚未安装，请在项目中运行 npm install yjs。如果您使用 NPM，这应该会自动发生（因为它会自动解析对等依赖关系）。

设置

设置	类型	默认值
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: [
    // ...
    Snapshot.configure({
      provider,
    }),
  ],
})

存储版本更新

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

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

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

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Snapshot.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: [
    // ...
    Snapshot.configure({
      provider,
    }),
  ],
})

const latestVersion = editor.storage.snapshot.latestVersion
const currentVersion = editor.storage.snapshot.currentVersion
const versions = editor.storage.snapshot.versions
const autoversioningEnabled = editor.storage.snapshot.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-snapshot'

// 配置提供程序
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
  }
})