安装“跟踪更改”扩展

安装并配置修订跟踪扩展,按照本指南操作。

安装

修订记录是一个不包含在任何套餐中的付费附加组件。你可以在免费试用期间测试,或在控制台中购买。

然后按照私有注册表指南配置你的包管理器。

然后,安装该软件包:

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

基本设置

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' },
    }),
  ],
})

设置

enabled

启用或禁用跟踪更改模式。启用时,所有编辑都会变成建议,而不是直接更改。

默认值:false

TrackedChanges.configure({
  enabled: true,
})

userId

当前进行建议的用户 ID。应来自您的身份验证系统。

默认值:'anonymous'

TrackedChanges.configure({
  userId: 'user-123',
})

userMetadata

关于当前用户的任意元数据,作为 JSON 可序列化对象存储在每个建议中。用于存储显示名称、头像或其他自定义数据,无需单独的用户存储。

默认值:null

TrackedChanges.configure({
  userId: 'user-123',
  userMetadata: {
    name: 'John Doe',
    avatar: 'https://example.com/avatar.jpg',
    role: 'editor',
  },
})

nodeTypeChangeTypes

符合节点类型建议的文本块的架构名称。包括源类型和目标类型。将段落转换为标题后会创建一个 attributeChange 建议,同时保留一份文本副本。配置对之外的转换将保留现有的替换行为。

默认值:[]

TrackedChanges.configure({
  nodeTypeChangeTypes: ['paragraph', 'heading'],
})

选择加入 nodeTypeChangeTypes 设置适用于本地编辑器。使用 Tiptap Collaboration(Y.js 文档)时,请将其保留为默认 [] 以继续跟踪类型转换作为替换。使用 Tiptap Collaboration(Y.js 文档)配置非空列表会在编辑器初始化期间抛出异常。请参阅节点类型更改,了解支持的转换和审核行为。

onSuggestionCreate

创建新建议时触发的回调。接收包含 id、type、userId、createdAt、from、to 和 text 的建议对象。

默认值:undefined

TrackedChanges.configure({
  onSuggestionCreate: (suggestion) => {
    console.log('已创建新建议:', suggestion)
    // 更新你的界面,通知其他用户等。
  },
})

onSuggestionAccept

接受建议时触发的回调。接收建议 ID。

默认值:undefined

TrackedChanges.configure({
  onSuggestionAccept: (id) => {
    console.log('建议已接受:', id)
  },
})

onSuggestionReject

拒绝建议时触发的回调。接收建议 ID。

默认值:undefined

TrackedChanges.configure({
  onSuggestionReject: (id) => {
    console.log('建议已拒绝:', id)
  },
})

blockSplitMarker

显示在建议的块拆分位置的标记。它会渲染在拆分前的块末尾。

默认值:'¶'

传入字符串以更改字符:

TrackedChanges.configure({
  blockSplitMarker: '↵',
})

传入元素或返回元素的函数,以完全控制标记的标记结构:

TrackedChanges.configure({
  // 函数每个标记调用一次,并且每次都必须返回一个新元素
  blockSplitMarker: () => {
    const marker = document.createElement('span')

    marker.className = 'my-split-marker'
    marker.textContent = '¶'

    return marker
  },
})

传入 null 可完全不渲染标记:

TrackedChanges.configure({
  blockSplitMarker: null,
})

单个 HTMLElement 也可以使用,并且会为每个标记克隆该元素。无论返回什么,扩展都会为其设置 data-tracked-change-split="true" 和 contenteditable="false",并禁用选择和指针事件,因此该标记永远不会成为可编辑内容。有关默认 CSS,请参阅样式设置。