配置评论

评论嵌入在协作云中的文档内。要启用评论,请集成 TiptapCollabProvider 并配置您的设置以支持评论功能。

提供者

TiptapCollabProvider 实例

默认值: null

const tiptapCollabProvider = new TiptapCollabProvider({
  // 您的提供者选项
})

Comments.configure({
  provider: tiptapCollabProvider,
})

类别

用于线程的类。

默认值:

{
  thread: 'tiptap-thread',
  threadInline: 'tiptap-thread--inline',
  threadBlock: 'tiptap-thread--block',
  threadHovered: 'tiptap-thread--hovered',
  threadSelected: 'tiptap-thread--selected',
  threadResolved: 'tiptap-thread--resolved',
  threadUnresolved: 'tiptap-thread--unresolved',
}
Comments.configure({
  classes: {
    thread: 'my-thread',
    threadInline: 'my-thread-inline',
    threadBlock: 'my-thread-block',
    threadHovered: 'my-thread-hovered',
    threadSelected: 'my-thread-selected',
    threadResolved: 'my-thread-resolved',
    threadUnresolved: 'my-thread-unresolved',
  },
})

onClickThread

点击线程时调用的回调。如果线程被点击,线程 ID 会传递给回调。如果没有点击任何线程,则传递 null。

默认值: undefined

Comments.configure({
  // ID 可以是字符串或 null
  onClickThread: (id) => console.log('线程被点击', id),
})

deleteUnreferencedThreads

一个布尔选项,用于控制是否删除文档中未引用的线程。默认情况下,当线程不再被文档引用时,它们会被标记为已删除。这对于清理不再需要的线程非常有用。

但是,如果您想保留这些线程,即使它们未被文档引用,您可以将此选项设置为 false。

默认值: true

Comments.configure({
  // 即使未被文档引用也保留线程
  deleteUnreferencedThreads: false,
})

配置 onThreadAnchorRemoved 后,该选项会替代自动清理。其 defaultHandler() 仍会遵循 deleteUnreferencedThreads 设置。

onThreadAnchorRemoved

当本地编辑移除线程在文档中的最后一个锚点时运行的回调。锚点可以是行内线程标记或块级线程节点。编辑完成后、清理流程更改线程数据前会运行此回调。它只会在执行编辑的客户端上运行,不会在远程接收更改的客户端上运行。

默认值: undefined,保留由 deleteUnreferencedThreads 控制的自动清理。

将此选项设为 false 可在锚点消失时禁用自动清理。除非回调调用 defaultHandler(),否则回调会替代清理流程。当 deleteUnreferencedThreads 为 true 时,默认处理程序会软删除不再被引用的线程。

例如,锚点消失时解决线程并保留其评论:

CommentsKit.configure({
  onThreadAnchorRemoved: ({ editor, threadId }) => {
    editor.commands.resolveThread({ id: threadId })
  },
})

回调会收到以下参数:

参数说明
editor线程最后一个锚点被移除的编辑器。
threadId线程 ID。
thread当前线程数据,包括其评论。
field包含此线程的协同字段。
removedBy'edit'、'command' 或 'undoRedo'。
defaultHandler运行已配置的默认清理流程。

使用 removeThread({ id }) 显式移除锚点时,removedBy 为 'command'。调用 removeThread({ id, deleteThread: true }) 会直接删除线程并跳过此回调。为修订跟踪建议创建的线程由该集成处理,也会跳过此回调。

请在回调中同步调用 defaultHandler()。它最多运行一次;回调返回后再调用则无效。例如,记录锚点移除并保留默认清理行为:

CommentsKit.configure({
  onThreadAnchorRemoved: ({ threadId, removedBy, defaultHandler }) => {
    console.log('Thread anchor removed', threadId, removedBy)
    defaultHandler()
  },
})

onThreadStateChanged

当 Yjs 事务更改编辑器协同字段中已有线程的状态后运行的回调。它会处理本地和远程更改。创建线程、添加评论或更新线程元数据不会触发此回调。

默认值: undefined,保留默认文档处理行为。永久删除线程会移除其锚点并保留锚点处的文本。解决、重新打开、软删除或恢复线程时会保留其锚点。

将此选项设为 false 可禁用线程状态变化时的自动文档处理。除非回调调用 defaultHandler(),否则回调会替代该处理流程。

CommentsKit.configure({
  onThreadStateChanged: ({ event, threadId, origin, defaultHandler }) => {
    console.log('Thread state changed', event, threadId, origin)
    defaultHandler()
  },
})

回调会收到以下参数:

参数说明
editor处理状态变化的编辑器。
threadId线程 ID。
event'resolved'、'unresolved'、'deleted' 或 'restored'。
previousThread更改前的线程数据。
thread更改后的线程数据。永久删除后,此值为 undefined。
field包含此线程的协同字段。
origin根据 Yjs 事务确定的 'local' 或 'remote'。
defaultHandler运行默认文档处理逻辑。请在回调中同步调用,且最多调用一次;回调返回后调用无效。

'deleted' 事件同时涵盖软删除和永久删除。'restored' 事件表示线程已从软删除状态恢复,不代表其文档锚点也已恢复。

例如,解决线程时移除锚点,但保留线程及其评论:

CommentsKit.configure({
  onThreadStateChanged: ({ editor, threadId, event, defaultHandler }) => {
    if (event === 'resolved') {
      editor.commands.removeThread({ id: threadId, deleteThread: false })
    }
    defaultHandler()
  },
})

在此回调中移除锚点不会触发 onThreadAnchorRemoved,也不会自动删除已脱离锚点的线程。在此回调中更改线程状态不会再次触发本地状态回调。重新打开线程不会重新创建由自定义处理移除的锚点。

trackedChangesIntegration

一个布尔选项,用于控制是否启用自动 跟踪更改 集成。启用后,会根据跟踪更改建议的生命周期事件自动创建、更新、解决或删除线程。

如果您不使用 Track Changes 扩展,并且想要防止注册任何相关事件监听器和 ProseMirror 插件,请将其设置为 false。

默认值: true

Comments.configure({
  // 如果你不使用那个扩展,请禁用 Track Changes 集成
  trackedChangesIntegration: false,
})

respectParentSchema

设置 respectParentSchema: true 后,块线程中的本地编辑必须遵循父节点的内容规则。例如,允许段落但不允许列表的 section 中的块线程不能包含列表。扩展能够保留文本时会转换单个无效文本块;无法修复的编辑会被拒绝。

现有的无效块线程不会迁移。只要子块类型不变,其中的文本仍可编辑。请在每个协作客户端上启用此选项。

默认值: false

CommentsKit.configure({
  respectParentSchema: true,
})

useLegacyWrapping

警告

新的包裹机制为块节点上的线程使用了不同的模式,这与之前的包裹行为不兼容。如果将此设置为 false 而未将现有线程节点映射到新模式,则线程内容将从文档中删除。

一个布尔选项,用于控制是否对多行评论使用遗留的包裹机制。我们建议新的实现将其设置为 false,现有集成可以保持之前的行为。这仅在与现有评论的向后兼容性方面是必要的,并且未来将被移除。

新的包裹机制更加灵活,允许更精确地包裹内容,并支持内联和块节点的混合包裹。

默认值: true

Comments.configure({
  // 启用新的灵活块包装
  useLegacyWrapping: false,
})