配置评论
评论嵌入在协作云中的文档内。要启用评论,请集成 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,
})