位置工具

位置工具帮助你在文档更改时跟踪和更新编辑器中的位置。

创建位置

使用 createMappablePosition 来创建一个位置实例。

// 在偏移量 10 处创建一个位置
const position = editor.utils.createMappablePosition(10)

createMappablePosition 方法默认返回一个 MappablePosition 实例。如果启用了协作扩展，它将返回一个 CollaborationMappablePosition 实例。

MappablePosition：用于在标准编辑器中跟踪位置的基础类
CollaborationMappablePosition：启用协作时用于跟踪位置的扩展类

更新位置

在事务之后，使用 getUpdatedPosition 来更新位置。位置会根据文档的更改更新。

// 在事务之后获取更新后的位置
const { position: updatedPosition, mapResult } = editor.utils.getUpdatedPosition(
  position,
  transaction,
)

// 更新后的位置反映了事务后的新位置
const newOffset = updatedPosition.position

getUpdatedPosition 方法返回一个包含以下属性的对象：

position（MappablePosition）：更新后的位置。
mapResult（MapResult | null）：映射操作的结果，作为 ProseMirror 的 MapResult。它包含操作的信息，例如用来判断位置是否被删除。

限制

当协作事务将一段落拆成两部分时，Y.js 视为删除段落的后半部分，然后插入一个新段落。因此，如果原始位置在换行符后，更新后的位置不会放在第二段，而是放在第一段的末尾。这是 Y.js 相对位置的限制，我们正在研究解决方案。

API 参考

`MappablePosition`

基础的 MappablePosition 类用于跟踪文档中的位置。

属性

position（number）：当前位置偏移量。

方法

`toJSON`

将位置序列化为 JSON 对象以便存储。

const position = editor.utils.createMappablePosition(10)
const json = position.toJSON()

// 存储到 localStorage 或发送到服务器
localStorage.setItem('savedPosition', JSON.stringify(json))

`fromJSON`

从 JSON 对象反序列化位置。

// 从存储中获取
const json = JSON.parse(localStorage.getItem('savedPosition'))

// 恢复位置
const position = MappablePosition.fromJSON(json)

示例：存储位置

import { MappablePosition } from '@tiptap/core'

// 创建并序列化一个位置
const position = editor.utils.createMappablePosition(25)
const json = position.toJSON()

// 存储它
localStorage.setItem('bookmark', JSON.stringify(json))

// 稍后恢复
const savedJson = JSON.parse(localStorage.getItem('bookmark'))
const restoredPosition = MappablePosition.fromJSON(savedJson)

`CollaborationMappablePosition`

CollaborationMappablePosition 扩展了 MappablePosition，支持 Y.js 相对位置以实现协作编辑。当启用协作扩展时会自动使用。

属性

position（number）：当前位置偏移量。
yRelativePosition（any）：Y.js 相对位置（内部使用，用于协作）。

方法

`toJSON`

将协作位置序列化为包括 Y.js 相对位置数据的 JSON 对象。

// 在协作编辑器中
const position = editor.utils.createMappablePosition(10)
const json = position.toJSON()

// json 包含 position 和 yRelativePosition
// 存储以便以后恢复
localStorage.setItem('collabPosition', JSON.stringify(json))

`fromJSON`

从 JSON 对象反序列化协作位置。

// 从存储中获取
const json = JSON.parse(localStorage.getItem('collabPosition'))

// 恢复位置（自动创建 CollaborationMappablePosition）
const position = CollaborationMappablePosition.fromJSON(json)

示例：存储协作位置

import { CollaborationMappablePosition } from '@tiptap/extension-collaboration'

// 在协作编辑器中创建一个位置
const position = editor.utils.createMappablePosition(42)

// 序列化以存储
const json = position.toJSON()
// json: { position: 42, yRelativePosition: [...] }

// 存储它
localStorage.setItem('collabBookmark', JSON.stringify(json))

// 稍后恢复
const savedJson = JSON.parse(localStorage.getItem('collabBookmark'))
const restoredPosition = CollaborationMappablePosition.fromJSON(savedJson)

PreviouslyJSX

Next up静态渲染器