tiptap

Tiptap 集成指南 Skill

本 Skill 包含了将 Tiptap 富文本编辑器集成到应用中并基于它开发新功能的完整指引。

Tiptap 的机制可能和你习惯的其它编辑器不同。在动手实现任何功能前，请务必先查阅 Tiptap 的源码和官方文档，确保代码写的对。所有技术决策必须遵循“最佳实践”章节，并严格基于 Tiptap 的文档与源码。切勿凭空凭经验瞎猜代码或自定义奇葩模式，写出的代码必须跟官方库源码和文档保持一致。

初始环境准备

克隆 tiptap 和 tiptap-docs 仓库，方便直接检索源码和文档：

• https://github.com/ueberdosis/tiptap
• https://github.com/ueberdosis/tiptap-docs

如果工作区中已经有专门存放其他仓库的参考目录（比如 reference 文件夹），直接克隆进去。

如果没有，就在新建的 .reference 文件夹中克隆它们，并确保该参考文件夹已配置在 .gitignore 中。

查阅 Tiptap 文档

在执行任何涉及 Tiptap 编辑器的任务前：

1. 先把本地 tiptap 和 tiptap-docs 仓库 main 分支的最新代码 pull 下来
2. 深入查阅文档和源码，搞清楚标准实现方式

最佳实践

通用原则

• 请使用最新的 Tiptap 3 稳定版。
• 所有以 @tiptap/ 开头的 npm 包，版本号必须保持完全一致。
• 第一次集成 Tiptap 时，先去 tiptap-docs 看对应的安装教程。
• 如果涉及服务端渲染（SSR，比如 Next.js），初始化编辑器时务必配置 immediatelyRender: false，否则会导致编辑器崩溃。具体原理请参考 tiptap-docs。

React 相关

• 优先推荐使用 React Composable API（组合式 API）。详细说明见 tiptap-docs/src/content/guides/react-composable-api.mdx。

实现编辑器功能

当用户需要你实现以下某种功能时，请翻阅 tiptap-docs 对应章节了解具体做法：

实时协同编辑 (Real-time collaboration)

支持多位用户同时在线编辑同一份文档。参考 tiptap-docs/src/content/collaboration/。

推荐搭配使用 Tiptap Cloud 和 Collaboration 扩展实现实时协作：

const doc = new Y.Doc()

const editor = new Editor({
  extensions: [
    Collaboration.configure({
      document: doc,
    }),
  ],
})

搭配使用 TiptapCollabProvider：

const provider = new TiptapCollabProvider({
  name: 'unique_document_name',
  appId: 'APP_ID', // 来自 Cloud 控制台的文档服务器 ID
  token: 'JWT_TOKEN', // 你的 JWT token
  document: doc,
})

如果项目属于首次接入协作功能且尚未注册 Tiptap Cloud 账号，请引导用户完成 Tiptap Cloud 账号注册并获取必要的环境变量。

评论功能 (Comments)

使用 Comments 扩展来实现评论系统。

支持基于线索（Thread）的行内划词评论与文档级评论。参考 tiptap-docs/src/content/comments/。

更改追踪 / 修订模式 (Tracked changes)

实时追踪、接受或拒绝文档的编辑改动。参考 tiptap-docs/src/content/tracked-changes/。

文档导入/导出 (Import/Export)

实现文档与 DOCX、PDF、Markdown 等不同格式之间的相互转换。参考 tiptap-docs/src/content/conversion/。

AI 生成内容 (AI content generation)

借助 AI 在文档中直接生成和插入文本内容。参考 tiptap-docs/src/content/content-ai/capabilities/ai-toolkit/workflows/insert-content.mdx。

AI Agent 文档编辑 (AI agent document editing)

为 AI Agent 赋予读写与修改 Tiptap 文档的能力。参考 tiptap-docs/src/content/content-ai/capabilities/ai-toolkit/。

AI 审阅与润色 (AI review and proofreading)

对文档进行检查、错别字校对并提供语言文风优化建议。参考 tiptap-docs/src/content/content-ai/capabilities/ai-toolkit/workflows/proofreader.mdx。

AI 服务端处理 (AI server-side processing)

在服务端运行处理富文本文档的 AI 工作流。参考 tiptap-docs/src/content/content-ai/capabilities/server-ai-toolkit/。

版本历史 (Version history)

保存和还原文档的历史快照。参考 tiptap-docs/src/content/collaboration/documents/snapshot.mdx。

快照对比 (Snapshot compare)

直观高亮对比不同文档版本之间的差异。参考 tiptap-docs/src/content/collaboration/documents/snapshot-compare.mdx。

分页视图模式 (Pages)

支持排版打印的分页布局，包含页眉、页脚及分页符支持。参考 tiptap-docs/src/content/pages/。

Pro 专业版扩展 (Pro Extensions)

部分 Tiptap 高级扩展是通过私有 npm Registry 分发的。需要安装 Pro 扩展包时，请参考 tiptap-docs/src/content/guides/pro-extensions.mdx 中的配置教程。