实用工具
该扩展导出用于查询建议和导出基础文档 JSON 的实用函数。
findSuggestions()
查找文档中的所有建议,并可选择性过滤。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
markName | string | 'suggestion' | 建议标记的名称 |
options | FindSuggestionsOptions | {} | 可选过滤条件(见下文) |
选项
| 选项 | 类型 | 说明 |
|---|---|---|
type | SuggestionType | 按建议类型过滤 |
userId | string | 按用户 ID 过滤 |
id | string | 按建议 ID 过滤 |
返回值
Suggestion[] — 在文档中找到的建议数组。
import { findSuggestions } from '@tiptap-pro/extension-tracked-changes'
// 查找所有建议
const allSuggestions = findSuggestions(editor)
// 按类型查找建议
const insertions = findSuggestions(editor, 'suggestion', { type: 'add' })
const deletions = findSuggestions(editor, 'suggestion', { type: 'delete' })
const replacements = findSuggestions(editor, 'suggestion', { type: 'replace' })
const splits = findSuggestions(editor, 'suggestion', { type: 'split' })
// 按用户查找建议
const userSuggestions = findSuggestions(editor, 'suggestion', { userId: 'user-123' })findSuggestionById()
通过 ID 查找特定建议。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
id | string | — | 要查找的建议 ID |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
Suggestion | undefined — 如果找到,则返回建议,否则返回 undefined。
import { findSuggestionById } from '@tiptap-pro/extension-tracked-changes'
const suggestion = findSuggestionById(editor, 'suggestion-123')
if (suggestion) {
console.log(`找到建议: ${suggestion.text}`)
}findSuggestionRanges()
查找由建议覆盖的所有文档范围。当建议跨越格式边界时,单个建议可能覆盖多个文本节点。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
id | string | — | 要查找的建议 ID |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
Array<{ from: number; to: number }> — 该建议覆盖的位置信息范围数组,相邻范围会自动合并。
import { findSuggestionRanges } from '@tiptap-pro/extension-tracked-changes'
const ranges = findSuggestionRanges(editor, 'suggestion-123')
// 返回: [{ from: 10, to: 25 }, { from: 30, to: 35 }]getSuggestionAtSelection()
获取当前光标选择位置的建议。支持基于标记的建议(文本)和基于属性的建议(原子节点)。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
Suggestion | undefined — 当前光标位置上的建议,若无则返回 undefined。
import { getSuggestionAtSelection } from '@tiptap-pro/extension-tracked-changes'
const suggestion = getSuggestionAtSelection(editor)
if (suggestion) {
// 在 UI 中显示接受/拒绝按钮
showSuggestionPopup(suggestion)
}getSuggestionAtPosition()
获取文档中特定位置的建议。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
pos | number | — | 要检查的文档位置 |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
Suggestion | null — 该位置的建议,如果未找到则返回 null。
import { getSuggestionAtPosition } from '@tiptap-pro/extension-tracked-changes'
const suggestion = getSuggestionAtPosition(editor, 42)findSuggestionsInRange()
查找与指定文档范围重叠的所有建议。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
from | number | — | 范围起始位置 |
to | number | — | 范围结束位置 |
filters | { userId?: string; type?: SuggestionType } | undefined | 可选过滤条件 |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
Suggestion[] — 与该范围重叠的建议数组。
import { findSuggestionsInRange } from '@tiptap-pro/extension-tracked-changes'
// 查找位置 10 到 50 之间的所有建议
const suggestions = findSuggestionsInRange(editor, 10, 50)
// 使用过滤条件
const userInsertions = findSuggestionsInRange(editor, 10, 50, {
userId: 'user-123',
type: 'add',
})suggestionExists()
检查建议是否仍存在于文档中。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
suggestionId | string | — | 要检查的建议 ID |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
boolean — 如果建议存在则返回 true。
import { suggestionExists } from '@tiptap-pro/extension-tracked-changes'
if (suggestionExists(editor, 'suggestion-123')) {
// 建议仍在文档中
}getSuggestionRange()
获取建议的边界位置范围。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
editor | Editor | — | Tiptap 编辑器实例 |
suggestionId | string | — | 建议 ID |
markName | string | 'suggestion' | 建议标记的名称 |
返回值
{ from: number; to: number } | null — 边界范围,若未找到则返回 null。
import { getSuggestionRange } from '@tiptap-pro/extension-tracked-changes'
const range = getSuggestionRange(editor, 'suggestion-123')
if (range) {
console.log(`建议覆盖范围从 ${range.from} 到 ${range.to}`)
}acceptSuggestions()
通过多个建议 ID 接受多条建议。逐条处理每个建议。
| 参数 | 类型 | 说明 |
|---|---|---|
editor | Editor | Tiptap 编辑器实例 |
suggestionIds | string[] | 要接受的建议 ID 数组 |
返回值
boolean — 如果至少接受了一条建议则返回 true。
import { acceptSuggestions } from '@tiptap-pro/extension-tracked-changes'
acceptSuggestions(editor, ['suggestion-1', 'suggestion-2', 'suggestion-3'])rejectSuggestions()
通过多个建议 ID 拒绝多条建议。逐条处理每个建议。
| 参数 | 类型 | 说明 |
|---|---|---|
editor | Editor | Tiptap 编辑器实例 |
suggestionIds | string[] | 要拒绝的建议 ID 数组 |
返回值
boolean — 如果至少拒绝了一条建议则返回 true。
import { rejectSuggestions } from '@tiptap-pro/extension-tracked-changes'
rejectSuggestions(editor, ['suggestion-1', 'suggestion-2'])withoutTrackedChanges()
通过拒绝副本上的每个待处理建议来返回基础文档。建议的添加内容将被删除,建议的删除内容将被恢复,并且替换内容将恢复为原始内容。挂起的格式、属性、节点类型、列表嵌套和块分割更改也将被还原。节点类型建议在其他建议被拒绝后恢复原始类型和属性,同时保留当前内容。
| 选项 | 类型 | 描述 |
|---|---|---|
content | string | JSONContent | HTML 或完整文档 JSON 对象。不支持 JSON 字符串和内容数组。 |
schema | Schema | 源文档的 ProseMirror 架构,包括 TrackedChanges 以及所有自定义节点和标记。 |
两个选项都是必需的。选项类型导出为 WithoutTrackedChangesOptions.
返回
JSONContent — 完整的文档 JSON 对象,没有建议标记或保留的跟踪属性,包括 null 跟踪默认值。其他内容、标记和属性在拒绝后按照架构所表示的方式保留。
该实用程序使输入和源编辑器保持不变,包括待处理的建议、选择、历史记录、回调、评论线程和协作提供程序。支持没有未决建议的内容。使用相同内容和架构重复导出会生成深度相等的 JSON。
import { withoutTrackedChanges } from '@tiptap-pro/extension-tracked-changes'
const base = withoutTrackedChanges({
content: editor.getJSON(),
schema: editor.schema,
})
// HTML input also returns JSON.
const baseFromHTML = withoutTrackedChanges({
content: editor.getHTML(),
schema: editor.schema,
})例如,在 Hello 之后等待插入 world 会生成仅包含 Hello 的基本 JSON。插入在源代码编辑器中保持待定状态。
无需编辑器即可使用
JSON 输入无需 DOM 即可工作。使用 getSchema 和源文档使用的相同扩展(包括自定义扩展)构建架构。
import { getSchema } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { TrackedChanges, withoutTrackedChanges } from '@tiptap-pro/extension-tracked-changes'
const schema = getSchema([StarterKit, TrackedChanges])
const base = withoutTrackedChanges({
content: { type: 'doc', content: [{ type: 'paragraph' }] },
schema,
})限制和错误
HTML 输入需要 DOM 环境并保留文本空白。自定义 HTML 渲染器必须保留解析器的建议数据以恢复基本内容。 HTML 无法恢复先前导出丢弃的数据或架构不支持的数据。
该实用程序会因无效文档 JSON、缺少跟踪架构支持或无法恢复的建议而引发错误。没有 DOM 的 HTML 输入也会抛出异常。如果导出失败,源内容保持不变。
内联原子建议必须使用节点属性。非文本节点上的建议标记会导致错误。显式列表嵌套增量必须是非零安全整数,对于 sink 为正整数,对于 lift 为负整数。旧文档仍支持省略或空增量。
仅恢复待处理的建议。该实用程序无法撤消已接受的更改或未经跟踪所做的编辑。
generateSuggestionId()
生成唯一的建议 ID。结合时间戳和随机字符串确保唯一性。
返回值
string — 格式为 suggestion-{timestamp}-{random} 的唯一建议 ID。
import { generateSuggestionId } from '@tiptap-pro/extension-tracked-changes'
const id = generateSuggestionId()
// 返回: 'suggestion-1706621696789-k7x2m9p'getTimestamp()
获取当前时间的 ISO 8601 格式时间戳字符串。
返回值
string — 当前时间的 ISO 8601 格式字符串。
import { getTimestamp } from '@tiptap-pro/extension-tracked-changes'
const timestamp = getTimestamp()
// 返回: '2024-01-30T12:34:56.789Z'getSuggestionHTMLAttributes()
从实时 ProseMirror 节点读取建议数据,并返回相应的 data-suggestion-* DOM 属性,可安全地展开到 NodeView 的根元素上。
| 参数 | 类型 | 说明 |
|---|---|---|
node | Node | 在你的 NodeView 组件中作为 node prop 接收的 ProseMirror 节点 |
返回值
SuggestionHTMLAttributes — 仅包含从 node.attrs 派生的 data-suggestion-* 属性的对象。值为 null 或 undefined 的键会被省略,因此非建议节点返回 {}。
生成的属性如下:
| 输出键 | 来源 (node.attrs) |
|---|---|
data-suggestion-id | suggestionId |
data-suggestion-type | suggestionType |
data-suggestion-user | suggestionUserId |
data-suggestion-created | suggestionCreatedAt |
data-suggestion-updated | suggestionUpdatedAt |
data-suggestion-user-metadata | suggestionUserMetadata(JSON 序列化) |
data-suggestion-nesting-delta | suggestionNestingDelta |
节点类型提案还会从 suggestionNodeTypeChange 生成 data-suggestion-node-type-change,即使删除或拆分使用节点的主要建议标识也是如此。对于独立类型提案,帮助器还提供常用的 attributeChange 身份属性。
Why node, not HTMLAttributes
NodeView 中的 HTMLAttributes prop 在创建时计算一次后就不会更新。将其传给此工具会在建议状态变化时产生过期属性——例如,在远程协作更新之后,或者某个建议被接受或拒绝时。node prop 是响应式的真实数据源,并且会在每次渲染时更新,因此请始终传入 node。
用法
import { getSuggestionHTMLAttributes } from '@tiptap-pro/extension-tracked-changes'
function MyNodeView({ node }) {
const suggestionAttrs = getSuggestionHTMLAttributes(node)
return (
<div {...suggestionAttrs}>
这里是你的内容
</div>
)
}有关将 NodeView 与 Tracked Changes 集成的详细指南,请参阅 NodeView 支持指南。