类型

Paid add-on

该扩展导出了用于处理建议的 TypeScript 类型。

SuggestionType

查询 API 返回的公开建议类型：

type SuggestionType = 'add' | 'delete' | 'replace' | 'markChange'

SuggestionMarkType

存储在建议标记上的内部标记级别类型。替换建议为其删除和插入部分使用不同的标记类型：

type SuggestionMarkType = 'add' | 'delete' | 'replaceDeletion' | 'replaceInsertion' | 'markChange'

SuggestionMarkChangeOperation

存储在标记更改建议中的操作：

type SuggestionMarkChangeOperation = 'added' | 'removed'

SuggestionMarkChange

描述存储在 markChange 建议上的一个标记变更：

type SuggestionMarkChange = {
  operation: SuggestionMarkChangeOperation
  markName: string
  markAttrs: Record<string, unknown> | null
}

Suggestion

表示文档中发现的建议：

type Suggestion = {
  id: string
  type: SuggestionType
  userId: string
  createdAt: string
  userMetadata: Record<string, unknown> | null
  from: number
  to: number
  text: string
  // 仅针对 'replace' 建议存在：
  deletionRange?: { from: number; to: number }
  insertionRange?: { from: number; to: number }
  replacedText?: string
  // 仅存在于 'markChange' 建议中：
  markChanges?: SuggestionMarkChange[]
  // 仅在建议影响块级节点时存在：
  insertedNodes?: JSONContent[]
  deletedNodes?: JSONContent[]
}

对于 replace 建议：

text 包含新（插入的）文本
replacedText 包含旧（删除的）文本
deletionRange 和 insertionRange 给出每部分的确切位置
from 和 to 覆盖两部分的完整范围

对于 markChange 建议：

text 包含受影响的文本内容
markChanges 包含跟踪的标记操作，包括标记名称和属性

对于块级节点建议（例如插入或删除一个段落或标题）：

text 始终包含受影响节点的实际文本内容——绝不使用 [nodeName] 占位符
insertedNodes 包含每个插入节点的完整 JSON 表示
deletedNodes 包含每个删除节点的完整 JSON 表示

在构建更丰富的 UI 时，请使用 insertedNodes 和 deletedNodes 来检查节点类型和属性，例如在建议文本旁显示节点类型徽标。

SuggestionMarkAttrs

存储在建议标记上的属性：

type SuggestionMarkAttrs = {
  id: string
  type: SuggestionMarkType
  userId: string
  createdAt: string
  userMetadata: Record<string, unknown> | null
  markChanges?: SuggestionMarkChange[] | null
}

SuggestionChangedEventPayload

trackedChanges:suggestionChanged 事件的载荷。每当建议中任何包含内容的字段发生变化时触发，包括范围位置、文本、标记变更或类型。

type SuggestionChangedEventPayload = {
  suggestionId: string
  oldSuggestion: Suggestion
  suggestion: Suggestion
  transaction: Transaction
}

oldSuggestion — 变更前建议的快照
suggestion — 当前（更新后的）建议
transaction — 导致变更的 ProseMirror 事务

SuggestionRangeChangedEventPayload

trackedChanges:suggestionRangeChanged 事件的载荷。仅在建议的文档位置发生偏移时触发。

type SuggestionRangeChangedEventPayload = {
  suggestionId: string
  oldRange: { from: number; to: number }
  newRange: { from: number; to: number }
  suggestion: Suggestion
  transaction: Transaction
}

TrackedChangesOptions

扩展的配置选项：

type TrackedChangesOptions = {
  enabled: boolean
  userId: string
  userMetadata?: Record<string, unknown> | null
  suggestionGroupingTimeout: number
  ignoredTrackingMarks: string[]
  onSuggestionCreate?: (suggestion: Suggestion) => void
  onSuggestionAccept?: (id: string) => void
  onSuggestionReject?: (id: string) => void
}

类型辅助

该扩展导出了用于处理建议类型的常量和辅助函数：

import {
  SUGGESTION_TYPES,
  isAddLikeType,
  isDeleteLikeType,
  isReplaceMarkType,
  markTypeToSuggestionType,
} from '@tiptap-pro/extension-tracked-changes'

// 常量
SUGGESTION_TYPES.ADD              // 'add'
SUGGESTION_TYPES.DELETE           // 'delete'
SUGGESTION_TYPES.REPLACE_DELETION  // 'replaceDeletion'
SUGGESTION_TYPES.REPLACE_INSERTION // 'replaceInsertion'
SUGGESTION_TYPES.MARK_CHANGE      // 'markChange'

// 检查标记类型是否表示添加内容（匹配 'add' 和 'replaceInsertion'）
isAddLikeType('add') // true
isAddLikeType('replaceInsertion') // true

// 检查标记类型是否表示删除内容（匹配 'delete' 和 'replaceDeletion'）
isDeleteLikeType('delete') // true
isDeleteLikeType('replaceDeletion') // true

// 检查标记类型是否为替换子类型之一
isReplaceMarkType('replaceDeletion') // true

// 将标记级别类型转换为公开建议类型
markTypeToSuggestionType('replaceDeletion') // 'replace'
markTypeToSuggestionType('add') // 'add'

Previously工具函数

Next up样式