类型

Compare 包导出用于处理 changeset、变化、差异建议、文档历史和序列化 schema 的 TypeScript 类型。工具函数和命令的参数接口会在各自的 API 中说明。

`TrackedChangeMetadata`

存储在由 changeset 创建的修订记录中的元数据。

interface TrackedChangeMetadata extends ChangeMetadata {
  id: string
  type: 'add' | 'delete' | 'replace' | 'markChange'
  userId: string | null
  createdAt: string | null
  updatedAt: string | null
  userMetadata: unknown
  markChanges?: TrackedChangeMarkMutation[]
}

TrackedChangeMarkMutation 描述一次格式变化，包含 operation（'added' | 'removed'）、markName 和 markAttrs。

`TrackedChangeData`

将编码后的修订记录元数据与其在生成文档中的范围配对。

interface TrackedChangeData {
  metadata: TrackedChangeMetadata
  range: Range
}

`TrackedChangesDocumentFactoryResult`

TrackedChangesDocumentFactory.fromChangeset 返回的结果。

interface TrackedChangesDocumentFactoryResult {
  doc: JSONContent
  trackedChanges: TrackedChangeData[]
}

`JSONFragment`

ProseMirror 片段的 JSON 表示。

type JSONFragment = JSONContent[] | null

`ChangesetJSON`

Changeset 的可 JSON 序列化表示。

interface ChangesetJSON {
  fragmentA: JSONFragment
  fragmentB: JSONFragment
  changes: Change[]
}

`ChangeMetadata`

附加到变化或文档步骤的任意元数据。

/**
 * Arbitrary non-null metadata attached to a step.
 *
 * The metadata is treated as a shallow object when comparing adjacent steps.
 */
type ChangeMetadata = Record<string, unknown>

`Change`

表示两个文档之间的一项差异。

/**
 * Represents a single change between two documents.
 */
interface Change {
  /** The range in the original document (`docA`) that changed. */
  rangeA: Range
  /** The matching range in the changed document (`docB`). */
  rangeB: Range
  /** The content scope. Default: `'inline'`. */
  scope?: ChangeScope
  /** Whether multiple inline changes were grouped into one block-level change. */
  isInlineGroup?: boolean
  /** Metadata associated with the step that produced this change. */
  metadata?: ChangeMetadata
  /** Later changes contained inside this change. */
  nestedChanges?: NestedChange[]
}

`ChangeScope`

变化覆盖行内内容还是块级内容。

type ChangeScope = 'inline' | 'block'

`NestedChange`

包含在父级 Change 中的后续变化。其范围是最终文档（docB）中的绝对位置。

interface NestedChange {
  range: Range
  metadata: ChangeMetadata
  scope: ChangeScope
}

`DiffOptions`

控制文档和片段比较的计算方式。

/** Options that control filtering and diff behavior. */
type DiffOptions = {
  /** Simplify nearby changes in inline mode. Default: `false`. */
  simplifyChanges?: boolean
  /** Attributes to remove before comparison. Default: `['id', 'data-thread-id', '_hash']`. */
  ignoreAttributes?: string[]
  /** Marks to remove before comparison. Default: `['inlineThread']`. */
  ignoreMarks?: string[]
  /** Node types to unwrap or remove before comparison. */
  ignoreNodes?: string[]
  /** Minimum unchanged range that separates changes. Default: `5`. */
  changeMergeDistance?: number | null
  /** Threshold for grouping inline changes into a block-level change in smart mode. Default: `2`. */
  groupInlineChanges?: number
  /** Comparison mode. Default: `'smart'`. */
  mode?: 'inline' | 'block' | 'smart'
  /** Node types whose full inline changes should become block changes. */
  expandBlockChanges?: string[]
}

`DiffSuggestion`

表示在编辑器中显示的提议替换。

/** A proposed change to a range of editor content. */
interface DiffSuggestion {
  /** A unique identifier for the suggestion. */
  id: string
  /** The range of editor content affected by the suggestion. */
  range: Range
  /** The replacement content. */
  content: Slice
  /** Optional custom metadata. */
  metadata?: Record<string, any>
  /** Options for rendering the suggestion. */
  displayOptions?: DisplayOptions
  /** Whether the suggestion groups multiple inline changes. */
  isInlineGroup?: boolean
  /** A range that can be mapped through document transactions. */
  mappableRange?: MappableRange
  /** Informational changes displayed inside this suggestion. */
  nestedChanges?: DiffSuggestionNestedChange[]
}

`DiffSuggestionNestedChange`

包含在差异建议中的嵌套变化。

interface DiffSuggestionNestedChange extends NestedChange {
  mappableRange?: MappableRange
}

`DisplayOptions`

控制差异建议的默认渲染方式。

/** Options for how to display a diff suggestion in the editor. */
interface DisplayOptions {
  /** Whether to show replacement content. Default: `true`. */
  showReplacement?: boolean
  /** Whether to show sub-changes in inline groups. Default: `true`. */
  showSubChanges?: boolean
  /** Extra HTML attributes for the original-content decoration. */
  attributes?: Record<string, any>
  /** Extra HTML attributes for the replacement decoration. */
  replacementAttributes?: Record<string, any>
  /** Extra HTML attributes for inline sub-change decorations. */
  subChangeAttributes?: Record<string, any>
  /** Extra HTML attributes for sub-changes inside replacement content. */
  replacementSubChangeAttributes?: Record<string, any>
  /** Returns HTML attributes for an explicit nested change. */
  getNestedChangeAttributes?: (options: NestedChangeAttributesOptions) => Record<string, string>
  /** A function that renders the suggestion as ProseMirror decorations. */
  renderDecorations?: RenderDecorations
}

getNestedChangeAttributes receives the nested change, its actionable parent suggestion, and whether that parent is selected. If it returns a class, Compare appends it to the default nested-change classes.

interface NestedChangeAttributesOptions {
  nestedChange: DiffSuggestionNestedChange
  suggestion: DiffSuggestion
  isSelected: boolean
}

自定义装饰渲染

将这些类型与 DisplayOptions.renderDecorations 一起使用，以替换或调整默认渲染。

/** Options passed to `defaultRenderDecorations`. */
interface DefaultRenderDecorationsOptions {
  /** Whether to render the main content and sub-change decorations. Default: `true`. */
  showMainDecorations?: boolean
  /** Whether to render replacement content. Default: `true`. */
  showReplacement?: boolean
  /** Whether to render sub-changes in inline groups. Default: `true`. */
  showSubChanges?: boolean
  /** Extra HTML attributes for the original-content decoration. */
  attributes?: Record<string, any>
  /** Extra HTML attributes for the replacement decoration. */
  replacementAttributes?: Record<string, any>
  /** Extra HTML attributes for inline sub-change decorations. */
  subChangeAttributes?: Record<string, any>
  /** Extra HTML attributes for sub-changes inside replacement content. */
  replacementSubChangeAttributes?: Record<string, any>
}

/** Values passed to a custom diff-suggestion renderer. */
interface RenderDecorationsOptions {
  /** The range occupied by the suggestion. */
  range: Range
  /** Whether the suggestion is selected. */
  isSelected: boolean
  /** The suggestion being rendered. */
  suggestion: DiffSuggestion
  /** Renders the default decorations, optionally with overridden options. */
  defaultRenderDecorations: (options?: DefaultRenderDecorationsOptions) => Decoration[]
}

/** A function that renders a suggestion as ProseMirror decorations. */
type RenderDecorations = (options: RenderDecorationsOptions) => Decoration[]

`Step`

表示 StepSequence 中的一次转换。

/** One document transition in a step sequence. */
interface Step {
  /** Document state before the step was applied. */
  before: Node
  /** Document state after the step was applied. */
  after: Node
  /** Metadata associated with the step. */
  metadata: ChangeMetadata
  /** Cached changes, or `null` when they need to be computed. */
  changes: Change[] | null
  /** Cached affected area, or `null` when unavailable. */
  changedArea: Change | null
}

`StepSequenceJSON`

StepSequence 的可 JSON 序列化状态。

/** JSON-serializable state for a step sequence. */
type StepSequenceJSON = {
  /** Document state before any steps were applied. */
  before: ReturnType<Node['toJSON']>
  /** Document states after each recorded step. */
  docs: Array<ReturnType<Node['toJSON']>>
  /** Metadata for each recorded step. */
  metadata: ChangeMetadata[]
  /** Cached changes for each recorded step. */
  changes: Array<Change[] | null>
  /** Cached affected areas for each recorded step. */
  changedAreas: Array<Change | null>
}

Previously工具函数

Next up样式