---
title: "工具函数"
description: "Tiptap Compare 包导出的工具函数。"
canonical_url: "https://tiptap.zhcndoc.com/compare/api-reference/utilities"
---

# 工具函数

Tiptap Compare 包导出的工具函数。

`@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](https://tiptap.zhcndoc.com/compare/api-reference/types.md#diffoptions).

### Returns (`Changeset`)

返回包含两个文档及其变化的 changeset。请参阅 [Changeset](https://tiptap.zhcndoc.com/compare/api-reference/utilities.md#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](https://tiptap.zhcndoc.com/compare/api-reference/utilities.md#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](https://tiptap.zhcndoc.com/compare/api-reference/utilities.md#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](https://tiptap.zhcndoc.com/compare/api-reference/utilities.md#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 节点视图](https://tiptap.zhcndoc.com/editor/extensions/custom-extensions/node-views.md) 是否位于差异建议中，并返回建议上下文。

### 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](https://prosemirror.net/docs/ref/#model.Slice) 渲染为用于差异显示的文档片段。

### Parameters (`RenderSliceToHtmlOptions`)

- `slice` ([`Slice`](https://prosemirror.net/docs/ref/#model.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`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment))

返回包含渲染后片段的[文档片段](https://developer.mozilla.org/en-US/docs/Web/API/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` 编码为[修订记录](https://tiptap.zhcndoc.com/tracked-changes/getting-started/overview.md)的 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.