UniqueID 扩展
UniqueID 扩展为你配置的节点类型添加唯一 ID。
该扩展会跟踪你的节点,即使你拆分它们、合并它们、撤销/重做更改、裁剪内容、粘贴内容……它都能正常工作。
此外,你可以配置哪些节点类型获得唯一 ID,哪些不获得,且可以自定义这些 ID 的生成方式。
安装
npm install @tiptap/extension-unique-id设置
attributeName
附加到 HTML 标签上的属性名称(前缀会是 data-)。
默认值:'id'
UniqueID.configure({
attributeName: 'uid',
})types
所有应获得唯一 ID 的节点类型,例如 ['heading', 'paragraph']。
你也可以传入 'all',为文档中除 doc 和 text 之外的所有节点类型添加 ID。
默认值:[]
UniqueID.configure({
types: ['heading', 'paragraph'],
})UniqueID.configure({
types: 'all',
})generateID
用于生成并返回唯一 ID 的函数。该函数接收一个上下文对象(例如 { node, pos }),因此你可以根据节点的类型或其位置自定义 ID 的生成方式。
默认值:({ node, pos }) => uuidv4()
UniqueID.configure({
generateID: ({ node }) => `${node.type.name}-${uuidv4()}`,
})filterTransaction
忽略某些事务,例如通过协作插件由其他用户应用的事务。
默认值:null
import { isChangeOrigin } from '@tiptap/extension-collaboration'
// 添加对协同编辑的支持
UniqueID.configure({
filterTransaction: (transaction) => !isChangeOrigin(transaction),
})updateDocument
是否通过为节点添加唯一 ID 来更新文档。如果文档处于只读模式、不可变,或者你不希望它被修改,可以将此属性设置为 false。
默认值:true
UniqueID.configure({
updateDocument: false,
})与协作(Collaboration)一起使用
重要
将 UniqueID 扩展与 Collaboration 扩展搭配使用时,请确保协作 provider 完成同步之后再挂载编辑器。在尚未同步的 Y.Doc 上挂载编辑器可能导致非预期的文档状态(例如持续存在的空段落),而 UniqueID 扩展会保留这些状态。
不正确的设置
在此示例中,编辑器在 provider 完成同步之前就立即挂载了 Collaboration 扩展。这会导致编辑器基于空的 Y.Doc 初始化,并引发非预期的文档修改。
import Collaboration from '@tiptap/extension-collaboration'
import { isChangeOrigin } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { useEffect } from 'react'
import * as Y from 'yjs'
const doc = new Y.Doc()
export default () => {
// ❌ Editor is mounted before the provider has synced
const editor = useEditor({
extensions: [
// ...other extensions
UniqueID.configure({
types: ['paragraph', 'heading'],
filterTransaction: (transaction) => !isChangeOrigin(transaction),
}),
Collaboration.configure({
document: doc,
}),
],
content: '<p>Initial content</p>', // This will be duplicated on every sync
})
useEffect(() => {
// Provider connects and syncs after the editor is already mounted
const provider = new TiptapCollabProvider({
name: 'your-document-name',
appId: 'YOUR_APP_ID',
token: 'YOUR_JWT',
document: doc,
})
}, [])
return <EditorContent editor={editor} />
}正确的设置
为避免此问题,请按以下顺序初始化:
- 初始化
Y.Doc - 启动协作 provider
- 等待
synced事件 - 检查协作文档是否为空
- 使用正确的内容挂载编辑器
import Collaboration from '@tiptap/extension-collaboration'
import { isChangeOrigin } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { useEffect } from 'react'
import * as Y from 'yjs'
const doc = new Y.Doc()
export default () => {
const editor = useEditor({
extensions: [
// ...other extensions
UniqueID.configure({
types: ['paragraph', 'heading'],
filterTransaction: (transaction) => !isChangeOrigin(transaction),
}),
Collaboration.configure({
document: doc,
}),
],
// Do not set content here — wait for sync
})
useEffect(() => {
const provider = new TiptapCollabProvider({
name: 'your-document-name',
appId: 'YOUR_APP_ID',
token: 'YOUR_JWT',
document: doc,
onSynced() {
// Only seed content if the collaborative document is empty
const isEmpty = doc.getXmlFragment('default').length === 0
if (isEmpty && editor) {
editor.commands.setContent(yourInitialContent)
}
},
})
}, [])
return <EditorContent editor={editor} />
}关键要点
- 不要在同步之前初始化编辑器内容。 使用协作时不要依赖默认编辑器状态。
- 使用
filterTransaction来忽略来自协作的变更。查看 filterTransaction 设置。 - 避免在开发过程中复用损坏的文档名称。 如果某个错误状态已经被持久化,请使用新的文档名称以干净地开始。
有关完整的协作设置指南,请参考 安装协作(Install Collaboration) 文档。
服务器端唯一 ID 工具
generateUniqueIds 函数允许你在服务端为 Tiptap 文档添加唯一 ID,无需创建 Editor 实例。这对于在服务端处理文档或需要为现有内容添加 ID 非常有用。
参数
doc(JSONContent):要添加唯一 ID 的 Tiptap JSON 文档extensions(Extensions):要使用的扩展列表。必须包含UniqueID扩展。若要自定义 ID 生成方式,可以向UniqueID扩展传入选项。
返回类型
返回添加了唯一 ID 后的新 Tiptap 文档(一个 JSONContent 对象)。
示例
import { generateUniqueIds, UniqueID } from '@tiptap/extension-unique-id'
import { StarterKit } from '@tiptap/starter-kit'
const doc = {
type: 'doc',
content: [
{ type: 'paragraph', content: [{ type: 'text', text: 'Hello, world!' }] },
{ type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'My Heading' }] },
],
}
const newDoc = generateUniqueIds(doc, [
StarterKit,
UniqueID.configure({ types: ['paragraph', 'heading'] }),
])
// 结果:
// {
// type: 'doc',
// content: [
// { type: 'paragraph', content: [{ type: 'text', text: 'Hello, world!' }], attrs: { id: 'd4590f81-52e8-45ec-b317-2e9a805b03e3' } },
// { type: 'heading', content: [{ type: 'text', text: 'My Heading' }], attrs: { level: 1, id: 'c88f9b5f-7b91-442f-b4d9-ee0d04104827' } }
// ]
// }该函数会自动获取 UniqueID 扩展中的配置,包括 types、attributeName 和 generateID 等选项。