Tiptap 中文文档

为 Pages 添加协作功能

Alpha

您可以通过将 Pages 扩展与协作提供者（例如 TiptapCollabProvider）结合使用，在分页编辑器中启用实时协作。

1. 需求

  • 支持协作的 Tiptap Pro 套餐
  • 可访问 Tiptap Cloud 或您自己的协作后端
  • Pages 栈：@tiptap-pro/extension-convert-kit、@tiptap-pro/extension-pages-tablekit、@tiptap-pro/extension-pages
  • 协作提供者：@tiptap-pro/provider（或您自己的实现），以及 @tiptap/extension-collaboration 和 yjs

2. 安装所需包 

npm install @tiptap-pro/extension-convert-kit \
            @tiptap-pro/extension-pages-tablekit \
            @tiptap-pro/extension-pages \
            @tiptap-pro/provider \
            @tiptap/extension-collaboration \
            yjs

3. 设置您的协作提供者 

import { TiptapCollabProvider } from '@tiptap-pro/provider'
import * as Y from 'yjs'

const doc = new Y.Doc()

const provider = new TiptapCollabProvider({
  name: 'document.name', // 用于同步的唯一文档标识符
  appId: 'your-app-id', // 来自 Cloud 控制台的文档服务器 ID，或在本地部署时使用 `baseURL`
  token: 'your-jwt', // 由您的服务器生成的 JWT
  document: doc,
})

4. 使用 Pages 栈和协作配置您的编辑器 

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
import { Pages } from '@tiptap-pro/extension-pages'
import Collaboration from '@tiptap/extension-collaboration'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      pageFormat: 'A4',
      header: 'My Project',
      footer: '第 {page} 页，共 {total} 页',
      // 将主编辑器的栈镜像到 header/footer 覆盖层中，以便
      // 其 schema、marks 和 tables 在那里表现一致。
      headerFooterExtensions: [ConvertKit.configure({ table: false }), TableKit],
    }),
    Collaboration.configure({
      document: doc,
    }),
  ],
})

页眉和页脚属于同一个会话

页眉和页脚编辑器会与主文档一起协作。无需额外的提供者配置；在编辑器上设置 Collaboration 就会将它们一并纳入。有关详细信息，请参见 页面页眉和页脚。

5. 流畅体验的小贴士

  • 确保在编辑前提供者已连接
  • 在您的 UI 中处理连接错误和用户存在状态
  • 可与其他协作扩展结合使用，例如评论、光标等
  • 传递给 headerFooterExtensions 的扩展应与主编辑器使用的相同，这样文档及其页眉页脚之间的 schema 才能保持一致

6. 后续步骤

PreviouslyPageKit