实用工具

该扩展导出用于查询建议和导出基础文档 JSON 的实用函数。

findSuggestions()

查找文档中的所有建议,并可选择性过滤。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
markNamestring'suggestion'建议标记的名称
optionsFindSuggestionsOptions{}可选过滤条件(见下文)

选项

选项类型说明
typeSuggestionType按建议类型过滤
userIdstring按用户 ID 过滤
idstring按建议 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 查找特定建议。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
idstring—要查找的建议 ID
markNamestring'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()

查找由建议覆盖的所有文档范围。当建议跨越格式边界时,单个建议可能覆盖多个文本节点。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
idstring—要查找的建议 ID
markNamestring'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()

获取当前光标选择位置的建议。支持基于标记的建议(文本)和基于属性的建议(原子节点)。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
markNamestring'suggestion'建议标记的名称

返回值

Suggestion | undefined — 当前光标位置上的建议,若无则返回 undefined。

import { getSuggestionAtSelection } from '@tiptap-pro/extension-tracked-changes'

const suggestion = getSuggestionAtSelection(editor)

if (suggestion) {
  // 在 UI 中显示接受/拒绝按钮
  showSuggestionPopup(suggestion)
}

getSuggestionAtPosition()

获取文档中特定位置的建议。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
posnumber—要检查的文档位置
markNamestring'suggestion'建议标记的名称

返回值

Suggestion | null — 该位置的建议,如果未找到则返回 null。

import { getSuggestionAtPosition } from '@tiptap-pro/extension-tracked-changes'

const suggestion = getSuggestionAtPosition(editor, 42)

findSuggestionsInRange()

查找与指定文档范围重叠的所有建议。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
fromnumber—范围起始位置
tonumber—范围结束位置
filters{ userId?: string; type?: SuggestionType }undefined可选过滤条件
markNamestring'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()

检查建议是否仍存在于文档中。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
suggestionIdstring—要检查的建议 ID
markNamestring'suggestion'建议标记的名称

返回值

boolean — 如果建议存在则返回 true。

import { suggestionExists } from '@tiptap-pro/extension-tracked-changes'

if (suggestionExists(editor, 'suggestion-123')) {
  // 建议仍在文档中
}

getSuggestionRange()

获取建议的边界位置范围。

参数类型默认值说明
editorEditor—Tiptap 编辑器实例
suggestionIdstring—建议 ID
markNamestring'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 接受多条建议。逐条处理每个建议。

参数类型说明
editorEditorTiptap 编辑器实例
suggestionIdsstring[]要接受的建议 ID 数组

返回值

boolean — 如果至少接受了一条建议则返回 true。

import { acceptSuggestions } from '@tiptap-pro/extension-tracked-changes'

acceptSuggestions(editor, ['suggestion-1', 'suggestion-2', 'suggestion-3'])

rejectSuggestions()

通过多个建议 ID 拒绝多条建议。逐条处理每个建议。

参数类型说明
editorEditorTiptap 编辑器实例
suggestionIdsstring[]要拒绝的建议 ID 数组

返回值

boolean — 如果至少拒绝了一条建议则返回 true。

import { rejectSuggestions } from '@tiptap-pro/extension-tracked-changes'

rejectSuggestions(editor, ['suggestion-1', 'suggestion-2'])

withoutTrackedChanges()

通过拒绝副本上的每个待处理建议来返回基础文档。建议的添加内容将被删除,建议的删除内容将被恢复,并且替换内容将恢复为原始内容。挂起的格式、属性、节点类型、列表嵌套和块分割更改也将被还原。节点类型建议在其他建议被拒绝后恢复原始类型和属性,同时保留当前内容。

选项类型描述
contentstring | JSONContentHTML 或完整文档 JSON 对象。不支持 JSON 字符串和内容数组。
schemaSchema源文档的 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 的根元素上。

参数类型说明
nodeNode在你的 NodeView 组件中作为 node prop 接收的 ProseMirror 节点

返回值

SuggestionHTMLAttributes — 仅包含从 node.attrs 派生的 data-suggestion-* 属性的对象。值为 null 或 undefined 的键会被省略,因此非建议节点返回 {}。

生成的属性如下:

输出键来源 (node.attrs)
data-suggestion-idsuggestionId
data-suggestion-typesuggestionType
data-suggestion-usersuggestionUserId
data-suggestion-createdsuggestionCreatedAt
data-suggestion-updatedsuggestionUpdatedAt
data-suggestion-user-metadatasuggestionUserMetadata(JSON 序列化)
data-suggestion-nesting-deltasuggestionNestingDelta

节点类型提案还会从 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 支持指南。