在你的编辑器中管理线程
使用本指南将评论直接集成到你的编辑器中。有关所有评论编辑器命令的完整列表,请参见 编辑器命令 页面。
你还可以通过我们的 评论 REST API 从编辑器外部与评论进行交互。
当锚点消失或线程状态发生变化时,你可以配置 onThreadAnchorRemoved 和 onThreadStateChanged,自定义相应行为。
了解线程
Tiptap 的评论功能将讨论组织成线程,通过区分线程和单个评论,使协作变得清晰且相关。
线程作为与特定文档部分相关的讨论容器,而评论表示在这些线程中的个体贡献。
创建新线程
假设你有一个按钮用于创建新线程。你可以使用 setThread 命令在当前选中位置创建一个新线程。
const createThread = () => {
editor
.chain()
.setThread({
content: '这是一个新线程', // 线程初始评论的内容
})
.run()
}这将会在当前选中位置创建一个新线程,并添加一个带有给定内容的评论。默认情况下,评论和线程没有分配用户或任何其他元数据。假设你想将作者添加到线程 和 评论中。你可以通过将 data 和 commentData 属性传递给 setThread 命令来实现。
const createThread = () => {
const user = {
id: '123', // 作者的用户 ID
name: 'John Doe', // 作者的名字
avatarUrl: 'https://example.com/avatar.jpg', // 作者的头像
}
editor
.chain()
.setThread({
content: '这是一个新线程', // 线程初始评论的内容
data: {
user,
},
commentData: {
user,
},
})
.run()
}现在线程和评论将会被分配给用户。
接收和监视线程及评论
使用 @tiptap-pro/extension-comments 中的 subscribeToThreads 保持线程列表最新。传入 editor 可在每个线程中包含其在文档中的当前范围。
回调会立即收到初始列表。传入编辑器后,线程数据或范围发生变化时,后续更新会在一个微任务中批量触发。本地编辑、协同编辑以及撤销或重做都会更新范围。仅选区变化不会触发回调。
import { subscribeToThreads } from '@tiptap-pro/extension-comments'
const unsubscribe = subscribeToThreads({
editor,
provider: yourTiptapCollabProvider,
callback: (threads) => {
console.log(threads.map((thread) => ({ id: thread.id, ranges: thread.ranges })))
},
getThreadsOptions: {
types: ['archived', 'unarchived'],
},
})默认情况下只返回未归档的线程。使用 getThreadsOptions.types 可包含已归档的线程,它们是软删除的线程。
传入 editor 后,订阅默认使用编辑器的协同字段。你可以通过 getThreadsOptions.field 指定其他字段。字段过滤也会包含尚未分配字段的旧版线程。
不再需要更新时调用 unsubscribe()。提供的编辑器销毁时,订阅也会自动清理。
不传入 editor 时,subscribeToThreads 返回不带 ranges 的 provider 线程记录,并且只监听 provider 的变化。
读取当前线程范围
使用 @tiptap-pro/extension-comments 中的 getThreads,读取带有编辑器中当前锚点的线程记录。编辑器必须安装 Comments 或 CommentsKit。
import { getThreads } from '@tiptap-pro/extension-comments'
const threads = getThreads({
editor,
provider: yourTiptapCollabProvider,
})每个结果都会保留 provider 的线程数据,并添加只读的 ranges 数组。该包导出了 ThreadWithPositions<Data, CommentData> 和 ThreadRange 类型。
每个范围包含以下字段:
| 字段 | 说明 |
|---|---|
from | 当前 ProseMirror 文档中的起始位置。 |
to | 当前 ProseMirror 文档中不包含在范围内的结束位置。 |
type | 标记范围为 'inline',块级线程包装节点为 'block'。 |
块级范围包含包装节点。一个线程可以有多个独立锚点,因此 ranges 可以包含多个按文档位置排序的条目。提供的编辑器中没有锚点的线程会返回 ranges: []。
这些位置描述的是当前文档中的位置,不是永久锚点。编辑后请重新读取,或在调用 subscribeToThreads 时传入 editor,以接收更新后的范围。
getThreads 接受与订阅相同的 getThreadsOptions 过滤器,并默认使用编辑器的协同字段。它会保留 provider 的顺序,不会按文档位置对线程排序。
要按文档顺序显示线程,请按第一个范围排序。以下示例会将没有锚点的线程排在最后,并使用线程 ID 打破并列:
const firstPosition = (thread) => thread.ranges[0]?.from ?? Infinity
const orderedThreads = [...threads].sort(
(left, right) => firstPosition(left) - firstPosition(right) || left.id.localeCompare(right.id),
)手动接收和渲染线程
要手动接收当前文档上的线程列表,你只需调用 provider.getThreads()。这将返回一个与您的提供者连接的文档中的线程数组。
这是一个静态数组,不会自动更新。如果你想保持线程列表的最新状态,你可以通过 provider.watchThreads 和 provider.unwatchThreads 函数监听更改。
// 将线程保存到一个变量中
let threads = []
// 每当线程发生变化时调用此函数
const getThreads = () => {
threads = provider.getThreads()
}
// 初始调用以获取线程
getThreads()
// 监视更改
provider.watchThreads(getThreads)要取消监视线程,你可以调用 provider.unwatchThreads(getThreads)。
provider.unwatchThreads(getThreads)watcher 回调还会收到 Yjs 事件和事务。使用 transaction.local 区分本地和远程更改;取消订阅时,将同一个回调传给 unwatchThreads:
const handleThreadChanges = (events, transaction) => {
console.log('Thread changes', events, transaction.local ? 'local' : 'remote')
}
provider.watchThreads(handleThreadChanges)
// 不再需要监视时取消订阅。
provider.unwatchThreads(handleThreadChanges)在 React 状态中维护线程范围
在 React 钩子中使用可感知编辑器的订阅,以接收线程数据和范围更新:
不传入 editor 时,这个钩子也可以正常工作,但收到的 provider 线程记录不包含 ranges。
import { subscribeToThreads } from '@tiptap-pro/extension-comments'
import { useEffect, useState } from 'react'
const useThreads = (provider, editor) => {
const [threads, setThreads] = useState([])
useEffect(() => {
if (!provider) {
return
}
return subscribeToThreads({
editor,
provider,
callback: setThreads,
})
}, [provider, editor])
return threads
}使用返回的线程渲染 UI。依赖项发生变化或组件卸载时,React 会调用取消订阅函数。
更新线程
要更新线程,你可以使用 updateThread 命令。该命令将使用给定 ID 更新线程并更新线程内容。
editor.commands.updateThread({
id: '123',
data: {
seen: true,
}
})这将更新 ID 为 123 的线程,并将 seen 属性设置为 true。
删除线程
要删除线程,你可以使用 removeThread 命令。该命令将删除具有给定 ID 的线程。
如何删除线程
默认情况下,已删除的线程不会从 yjs 文档中删除。要做到这一点,可以将
deleteThread 选项传递给 removeThread 命令。
editor.commands.removeThread({
id: '123',
deleteThread: true,
})创建、更新和删除评论
评论可以在线程内添加、编辑和删除,但不能标记为已解决,因为它们被视为线程讨论的一部分。
要在线程上创建评论,你可以使用 createComment 命令。该命令将在具有给定 ID 的线程上创建一条新评论。
editor.commands.createComment({
threadId: '123',
content: '这是一个新评论', // 这也可以是 tiptap JSON 或任何其他类型的内容
data: {
user, // 传递任何你想要的元数据 - 在这种情况下是用户
},
})这将在 ID 为 123 的线程上创建一条新评论,并将内容设置为 这是一个新评论。你还可以将任何元数据传递给评论。
要更新评论,你可以使用 updateComment 命令。该命令将更新具有给定 ID 的评论并更新评论内容。
editor.commands.updateComment({
threadId: '123', // 线程 ID
id: '456', // 评论 ID
content: '现在这是新内容', // 评论的新内容
data: {
edited: true, // 将 edited 属性设置为 true
},
})这将更新 ID 为 456 的评论,并将其内容设置为 现在这是新内容。你也可以传递任何你想要的元数据。
最后,你可以通过使用 deleteComment 命令删除评论。该命令将删除具有给定 ID 的评论。
editor.commands.deleteComment({
threadId: '123',
id: '456',
})解决和取消解决线程
要解决线程,你可以使用 resolveThread 命令。该命令将解决具有给定 ID 的线程。
editor.commands.resolveThread({
id: '123',
})这将解决 ID 为 123 的线程。要取消解决线程,你可以使用 unresolveThread 命令。该命令将取消解决具有给定 ID 的线程。
如果你想解决一个线程并添加有关解决该线程的用户的信息,可以设置线程数据以包含解决该线程的用户。在取消解决线程时,请务必清除数据。
editor.commands.unresolveThread({
id: '123',
})查找文档中的所有线程
要查找编辑器文档中的所有线程,你可以使用 findThreadsInDocument 工具函数。该函数返回包含所有线程节点和标记的数组,包括它们在文档中的位置。
const threads = findThreadsInDocument(editor, {
blockTypeName: 'blockThread',
markTypeName: 'inlineThread',
})这将返回一个线程对象数组,每个对象包含线程标识符、节点、它的位置以及可选的相关标记。
选择线程
要选择线程,你可以使用 selectThread 命令。该命令选择具有指定 ID 的线程。
editor.commands.selectThread({
id: '123',
})这将光标移动到 ID 为 123 的线程。
要取消选择线程,你可以使用 unselectThread 命令。该命令取消选择具有指定 ID 的线程。
editor.commands.unselectThread({
id: '123',
})你还可以选择或取消选择没有 ID 的线程。在这种情况下,编辑器将选择或取消选择当前选中的线程。