工具函数

@tiptap-pro/compare 包导出的类和函数列表。

Compare

Compare Tiptap 编辑器扩展。将它添加到渲染差异的编辑器中。此扩展不接受任何配置选项。

compareDocuments

比较两个 Tiptap JSON 文档。

Parameters (CompareDocumentsOptions)

• schema (Schema): The ProseMirror schema used to parse both documents.
• docA (JSONContent): The original document.
• docB (JSONContent): The changed document.
• diffOptions? (DiffOptions): Options that control the comparison. See DiffOptions.

Returns (Changeset)

返回包含两个文档及其变化的 changeset。请参阅 Changeset。

compareFragments

比较两个 Tiptap JSON 片段。

Parameters (CompareFragmentsOptions)

• schema (Schema): The ProseMirror schema used to parse both fragments.
• fragmentA (JSONContent[] | null): The original fragment.
• fragmentB (JSONContent[] | null): The changed fragment.
• diffOptions? (DiffOptions): Options that control the comparison.

Returns (Changeset)

返回包含两个片段及其变化的 changeset。请参阅 Changeset。

compareSteps

将 StepSequence 转换为不重叠的变化。

Parameters (CompareStepsOptions)

• stepSequence (StepSequence): The document transitions to compare.
• compareMetadata? ((a: ChangeMetadata, b: ChangeMetadata) => boolean): Decides whether adjacent steps can be grouped.
• diffOptions? (DiffOptions): Options that control the comparison.

Returns (Changeset)

返回包含初始文档、最终文档及其变化的 changeset。变化包含产生它们的步骤所关联的元数据。请参阅 Changeset。

compareVersions

比较两个完整的 Yjs v2 更新，并在可用时恢复协作元数据。

Parameters (CompareVersionsOptions)

• versionA (Uint8Array): The older Yjs v2 update.
• versionB (Uint8Array): The newer Yjs v2 update.
• schema (Schema): The schema used to hydrate both versions.
• diffOptions? (DiffOptions): Options that control the comparison.
• compareMetadata? ((a: ChangeMetadata, b: ChangeMetadata) => boolean): Decides whether adjacent changes can be grouped. By default, changes with the same userId are grouped.
• field? (string): The Yjs document field. Default: 'default'.
• permanentUserDataMapField? (string): The shared user-data map field. Default: '__tiptapcollab__users'.
• enableDebugging? (boolean): Enables extraction logging. Default: false.

Returns (Changeset)

返回包含两个版本及其变化的 changeset。变化包含来自变更历史的元数据，例如可用时的 userId。请参阅 Changeset。

Changeset

表示比较两个文档、片段、步骤或版本的结果。

Properties

• fragmentA (JSONFragment): The original fragment.
• fragmentB (JSONFragment): The modified fragment.
• changes (Change[]): The changes between both fragments.
• docA (JSONContent): The original document as a Tiptap JSON document.
• docB (JSONContent): The modified document as a Tiptap JSON document.

changeset.reverse

创建方向相反的 changeset，其中文档 A 变为文档 B，反之亦然。

Parameters

此方法没有参数。

Returns (Changeset)

• Changeset: A changeset with the original and modified documents reversed.

changeset.toJSON

序列化 changeset。

Parameters

此方法没有参数。

Returns (ChangesetJSON)

• fragmentA (JSONFragment): The original fragment.
• fragmentB (JSONFragment): The modified fragment.
• changes (Change[]): The changes between both fragments.

Changeset.fromJSON

从序列化 JSON 恢复 changeset。

Parameters

• json (ChangesetJSON): The serialized changeset.

Returns (Changeset)

• Changeset: The hydrated changeset.

findDiffSuggestions

返回当前在编辑器中显示的差异建议。

Parameters

• editor (Editor): The editor configured with Compare.

Returns (DiffSuggestion[])

每个 DiffSuggestion 包含：

• id (string): The suggestion ID.
• range (Range): The affected range in the editor.
• content (Slice): The replacement content.
• metadata? (Record<string, any>): Optional custom metadata.
• displayOptions? (DisplayOptions): Options used to render the suggestion.
• isInlineGroup? (boolean): Whether inline changes were grouped.
• mappableRange? (MappableRange): A range that can be mapped through transactions.
• nestedChanges? (DiffSuggestionNestedChange[]): Informational changes nested in this suggestion. Accept and reject actions target the parent suggestion.

getSuggestionNodeViewContext

判断 Tiptap 节点视图 是否位于差异建议中，并返回建议上下文。

Parameters

• decorations (Decoration[]): The decorations passed to the custom node view.

Returns (SuggestionNodeViewContext)

• suggestion (DiffSuggestion | null): The suggestion where the node view is located or null if the node view is not part of a diff suggestion.
• isSelected (boolean): Whether the suggestion is selected. A suggestion is selected when the cursor is inside the suggestion.
• isReplacement (boolean): Whether the node view is inside replacement content. It is false for content in the current document.

renderSlice

将 ProseMirror slice 渲染为用于差异显示的文档片段。

Parameters (RenderSliceToHtmlOptions)

• slice (Slice): The slice to render.
• editor (Editor): The editor used to render the slice.
• suggestionNodeViewContext (SuggestionNodeViewContext): Context data provided to custom node views while rendering.

Returns (DocumentFragment)

返回包含渲染后片段的文档片段。

generateSuggestionId

为差异建议创建唯一 ID。

Parameters

此工具没有参数。

Returns (string)

• string: A unique suggestion ID.

getVersions

从协作提供程序请求两个快照。

Parameters

• provider (TiptapCollabProvider): A provider with version-listing and stateless-message methods.
• fromVersion (number): The first version ID.
• toVersion? (number): The second version ID. Defaults to the latest version.

Returns (Promise<{ snapshot: Uint8Array; prevSnapshot: Uint8Array }>)

Promise 会解析为：

• snapshot (Uint8Array): The newer version update.
• prevSnapshot (Uint8Array): The older version update.

getDocumentFromVersion

从完整的 Yjs v2 更新恢复 Tiptap JSON 文档。

Parameters (GetDocumentFromVersionOptions)

• version (Uint8Array): The complete Yjs v2 update.
• schema (Schema): The schema used to hydrate the document.
• field? (string): The Yjs document field. Default: 'default'.

Returns (JSONContent)

返回的 JSON 文档包含：

• type (string): The Tiptap node type, usually 'doc' for a complete document.
• content? (JSONContent[]): The document's child nodes.
• attrs? (Record<string, any>): Attributes on the document node.
• marks? (Mark[]): Marks on the node, when applicable.
• text? (string): Text content, when applicable.

TrackedChangesDocumentFactory

创建一个将 Changeset 编码为修订记录的 Tiptap JSON 文档。在服务器或没有编辑器实例的环境中使用它。

fromChangeset

将 changeset 转换为包含修订记录的文档。

Parameters (TrackedChangesDocumentFactoryOptions)

• changeset (Changeset): The comparison result to encode.
• schema (Schema): The ProseMirror schema that includes the Tracked Changes extension.

Returns (TrackedChangesDocumentFactoryResult)

• doc (JSONContent): The document with tracked-change marks and node attributes.
• trackedChanges (TrackedChangeData[]): The encoded tracked changes and their ranges in doc.

serializeSchema

将 ProseMirror schema 序列化为可安全传输的 JSON 数据。

Parameters

• schema (Schema): The schema to serialize.

Returns (SerializedSchema)

编码为 JSON 对象的 Tiptap 编辑器 schema，可通过网络发送。

deserializeSchema

从序列化的 schema 数据创建 ProseMirror schema。

Parameters

• jsonSchema (SerializedSchema): The JSON-safe schema data to deserialize.

Returns (Schema)

• Schema: The hydrated ProseMirror schema.

StepSequence

存储一系列文档状态以及每次转换的元数据。

StepSequence.fromInitialDocument

创建空序列。

Parameters

• before (Node): The initial document.

Returns (StepSequence)

• before (Node): The initial document.
• after (Node): The latest document, initially the same as before.
• stepCount (number): The number of recorded steps, initially 0.

StepSequence.fromJSON

从 JSON 恢复序列。

Parameters (StepSequenceFromJSONOptions)

• json (StepSequenceJSON): The serialized sequence.
• schema (Schema): The schema used to hydrate its documents.

Returns (StepSequence)

• before (Node): The initial document.
• after (Node): The latest document.
• stepCount (number): The number of recorded steps.

sequence.addStep

追加一次文档转换。

Parameters (AddStepOptions)

• doc (Node): The document after the step.
• metadata (ChangeMetadata): Metadata for the step.
• changes? (Change[] | null): Cached changes. null means there are no cached changes so the diff will be computed. An empty array means there were no changes between the steps.
• changedArea? (Change | null): Cached changed area, when available.

Returns (void)

此方法不返回值。

sequence.copy and sequence.reverse

copy 复制序列。reverse 返回从最终文档回到初始文档的序列。

Parameters

这些方法没有参数。

Returns (StepSequence)

• before (Node): The initial document for the returned sequence.
• after (Node): The final document for the returned sequence.
• stepCount (number): The number of recorded steps.

sequence.getSteps

返回记录的每次文档转换。

Parameters

此方法没有参数。

Returns (Step[])

每个 Step 包含：

• before (Node): The document before the transition.
• after (Node): The document after the transition.
• metadata (ChangeMetadata): Metadata for the transition.
• changes (Change[] | null): Cached changes, when available.
• changedArea (Change | null): Cached changed area, when available.

sequence.toJSON

序列化序列。

Parameters

此方法没有参数。

Returns (StepSequenceJSON)

• before (JSONContent): The initial document.
• docs (JSONContent[]): Documents after each transition.
• metadata (ChangeMetadata[]): Metadata for each transition.
• changes (Array<Change[] | null>): Cached changes for each transition.
• changedAreas (Array<Change | null>): Cached changed areas for each transition.