TipTap

基于 ProseMirror 的现代无头富文本编辑器框架，为开发者提供完全可控的内容编辑体验。

技术简介说明

TipTap 是一个基于 ProseMirror 的无头（headless）富文本编辑器框架。与传统富文本编辑器不同，TipTap 不附带任何预设的 UI，它将编辑器的渲染逻辑与界面层彻底解耦，让开发者可以使用 React、Vue、Svelte 或原生 JavaScript 自由构建任意编辑器界面。

TipTap 的核心理念是"开发者体验优先"。它通过扩展系统自动处理 Schema 定义，提供命令式 API 进行内容操作，并内置了对协作编辑、AI 集成等现代功能的支持。2025 年 7 月，TipTap 3.0 正式发布，带来了 SSR 支持、JSX 支持、增强的 TypeScript 类型等重磅特性。

作为 2025–2026 年最受欢迎的现代编辑器框架之一，TipTap 的 npm 生态每月下载量超过 900 万次，被广泛应用于 SaaS 产品、内容管理系统、Notion 类编辑器等场景。

基本信息

• 官网：https://tiptap.dev/
• GitHub：https://github.com/ueberdosis/tiptap
• License：MIT（开源核心）/ 商业许可（协作、AI 等高级功能）
• 最新版本：v3.x（稳定版，2025 年 7 月发布）
• 主要维护者/公司：überdosis（德国，YC 校友企业）
• GitHub Stars：~36,500+
• npm 周下载量：核心包 ~42K，生态包合计 9M+/月
• 框架支持：React、Vue 3、Svelte、原生 JavaScript

快速上手

安装

# 核心包
npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
 
# React 集成
npm install @tiptap/react
 
# Vue 3 集成
npm install @tiptap/vue-3
 
# 常用扩展
npm install @tiptap/extension-bold @tiptap/extension-italic @tiptap/extension-underline
npm install @tiptap/extension-text-align @tiptap/extension-placeholder

基础配置

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
 
// StarterKit 3.0 已默认包含 Underline、Link、TrailingNode
const editor = useEditor({
  extensions: [
    StarterKit.configure({
      heading: {
        levels: [1, 2, 3],
      },
    }),
  ],
  content: '<p>Hello World! 🌍</p>',
  editorProps: {
    attributes: {
      class: 'prose prose-sm sm:prose lg:prose-lg xl:prose-2xl mx-auto focus:outline-none',
    },
  },
})

最小示例（React）

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
 
export default function App() {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World!</p>',
  })
 
  if (!editor) return null
 
  return (
    <div>
      <div className="toolbar">
        <button
          onClick={() => editor.chain().focus().toggleBold().run()}
          className={editor.isActive('bold') ? 'is-active' : ''}
        >
          Bold
        </button>
        <button
          onClick={() => editor.chain().focus().toggleHeading({ level: 1 }).run()}
          className={editor.isActive('heading', { level: 1 }) ? 'is-active' : ''}
        >
          H1
        </button>
        <button
          onClick={() => editor.chain().focus().toggleBulletList().run()}
          className={editor.isActive('bulletList') ? 'is-active' : ''}
        >
          Bullet List
        </button>
      </div>
      <EditorContent editor={editor} />
    </div>
  )
}

核心概念与架构

架构概览

TipTap 采用无头（headless）架构，将编辑器分为三层：

1. 核心层（Core）：基于 ProseMirror 的编辑器引擎，管理文档模型、状态和事务
2. 扩展层（Extensions）：通过扩展系统声明式地定义功能，自动处理 Schema
3. UI 层（Framework Bindings）：与 React/Vue/Svelte 的集成层，完全由开发者控制

核心概念

• 文档模型（Document Model）：基于 ProseMirror 的 JSON 文档模型，由 Node、Mark、Text 组成
• 扩展（Extensions）：TipTap 最重要的抽象，每个功能（粗体、斜体、列表等）都是一个扩展
• 命令（Commands）：可链式调用的操作 API，如 editor.chain().focus().toggleBold().run()
• 事务（Transactions）：所有状态变更都通过事务进行，保证状态一致性
• 节点视图（Node Views）：自定义节点的渲染方式，支持 React/Vue 组件

3.0 架构变化

• 放弃 UMD 构建，仅支持 ESM 和 CJS
• 引入 dispatchTransaction 扩展钩子，可在事务应用前拦截和修改
• 使用 Floating UI 替代 tippy.js 管理弹出层
• 合并相关扩展为统一包（如 TableKit）

核心特性

• 无头架构：不绑定任何 UI，完全自定义编辑器外观和交互
• 扩展系统：声明式扩展自动处理 Schema 定义，内置 100+ 开源扩展
• TypeScript 原生支持：强类型扩展存储和配置选项（3.0 大幅增强）
• SSR 支持：服务端渲染内容，无需 DOM 依赖
• JSX 支持：在 renderHTML 方法中使用 JSX 语法
• 链式命令 API：优雅的内容操作，支持链式调用
• 协作编辑：基于 Yjs 的实时协作（y-tiptap 包，需付费）
• AI 工具包：内置 AI Toolkit，支持 AI 建议和 AI Agent（2026 重点方向）
• 静态渲染：@tiptap/static-renderer 可输出 React 组件、HTML 或 Markdown
• React 性能优化：3.0 对 React 渲染进行了专项优化
• 删除检测：节点/标记删除事件监听器

生态图

关键依赖

• ProseMirror：底层编辑器引擎（prosemirror-state、prosemirror-view、prosemirror-model 等）
• Yjs：实时协作的 CRDT 基础
• Hocuspocus：TipTap 的协作后端服务

官方扩展生态

社区生态

• Tiptap Editor Suite：Dev Toolkit 商业套件
• Plate.js 迁移支持：提供从 Plate/Lexical/Quill 的迁移指南
• Tailwind Typography：常用样式集成方案

适用场景

• SaaS 产品内容编辑：博客、文档、公告等富文本编辑场景（最佳选择）
• Notion 类块编辑器：通过 Block 扩展构建类 Notion 编辑体验
• CMS 内容管理：与 Strapi、Sanity 等 Headless CMS 集成
• 协作编辑工具：多人实时文档协作（需 Tiptap Cloud 或自建 Hocuspocus）
• 邮件编辑器：利用 HTML 输出构建所见即所得的邮件编辑器
• 低代码/无代码平台：作为表单中的富文本输入组件
• AI 驱动的写作工具：利用 AI Toolkit 构建智能写作辅助

开发与工程化

开发流程

# 开发环境
npm run dev
 
# 构建
npm run build
 
# 类型检查
pnpm typecheck
 
# 测试
pnpm test

自定义扩展开发

import { Extension } from '@tiptap/core'
 
export const CustomExtension = Extension.create({
  name: 'customExtension',
 
  addOptions() {
    return { defaultOption: 'value' }
  },
 
  addCommands() {
    return {
      myCommand: () => ({ commands }) => {
        return commands.insertContent({ type: 'paragraph', content: [] })
      },
    }
  },
 
  addKeyboardShortcuts() {
    return {
      'Mod-Shift-x': () => this.editor.commands.myCommand(),
    }
  },
})

CI/CD 集成

• 支持 tree-shaking，按需引入扩展减小包体积
• 仅 ESM/CJS 构建（3.0 移除 UMD），确保构建工具兼容
• 推荐使用 pnpm 作为包管理器

性能与安全

性能特点

• 按需加载：通过 StarterKit 仅引入所需扩展，核心包体积小于 Quill、Slate、Lexical
• React 优化：3.0 版本专项优化了 React 渲染性能
• 虚拟滚动：大文档需要配合虚拟滚动方案
• 事务优化：避免在事务中遍历状态，遵循最佳实践可保持流畅

性能注意事项

• 忽略最佳实践（如在事务中遍历状态）可能导致明显卡顿
• 大型文档（>10,000 节点）需配合虚拟滚动
• 协作场景需要额外的 WebSocket 连接管理

安全注意

• 使用 DOMPurify 对输出 HTML 进行消毒
• 服务端渲染时注意 XSS 防护
• 用户输入内容始终在服务端进行校验

技术对比

最佳实践

1. 使用 StarterKit：从 StarterKit 开始，按需添加扩展，避免一次性引入所有功能
2. 遵循事务规范：不要在事务处理中遍历编辑器状态，使用 ProseMirror 的内置方法
3. 自定义扩展封装：将可复用的编辑器逻辑封装为扩展，保持组件层清洁
4. 服务端内容消毒：始终对编辑器输出的 HTML 进行 DOMPurify 处理
5. 按需加载扩展：利用 tree-shaking 仅引入需要的扩展，减小打包体积
6. React 中使用 useEditor：配合 EditorContent 组件，避免不必要的重渲染
7. 协作编辑规划：如需协作，从一开始就考虑数据模型和冲突解决方案

技术局限与边界

• 非开箱即用：无头设计意味着所有 UI 需要自行开发，初始投入较大
• 高级功能付费：协作编辑、AI 工具包等核心功能需要商业许可
• ProseMirror 依赖：底层绑定 ProseMirror，受限于 ProseMirror 的架构约束
• 无 UMD 构建：3.0 移除 UMD 格式，旧项目升级需要调整构建工具
• 大文档性能：超长文档需要额外的虚拟滚动优化
• 迁移成本：从其他编辑器迁移需要重新设计 Schema 和数据格式

学习资源

• 官方文档：https://tiptap.dev/docs/introduction
• React 指南：https://tiptap.dev/docs/editor/getting-started/react
• Vue 指南：https://tiptap.dev/docs/editor/getting-started/vue
• 扩展开发：https://tiptap.dev/docs/guide/custom-extensions
• GitHub 仓库：https://github.com/ueberdosis/tiptap
• 社区 Discord：https://discord.gg/tiptap
• Release Notes：https://tiptap.dev/blog/release-notes
• 2026 路线图：https://tiptap.dev/blog/release-notes/our-roadmap-for-2026

2026 年现状

最新版本

• 稳定版：v3.x（2025 年 7 月发布 3.0 稳定版后持续迭代）
• 发布频率：约每 4 天一个版本

发展趋势

TipTap 2026 年的核心愿景是成为**"围绕数据库的文档层"**：

1. AI 深度集成：AI Toolkit 和 Server AI Toolkit 让 AI Agent 实时访问和编辑文档
2. 双向 Markdown 支持：无缝的 Markdown ↔ TipTap 文档转换
3. Tracked Changes：Google Docs 风格的修改追踪
4. Pages & 分页：支持页眉页脚、结构化分页
5. Hocuspocus 4：协作后端重大稳定版本（2026 年 5 月）
6. Q1 2026 Hackathon：持续推进 AI 工具包和修改追踪

社区活跃度

• GitHub Stars：~36,500+
• npm 生态月下载量：9M+
• YC 背书，持续获得投资
• 开源社区活跃，100+ 开源扩展

定价（2026）

• Cloud 平台：$49–$999/月（按功能分级）
• Start 计划：基础协作编辑、AI 交互，500 文档限制
• Team 计划：更高限额和扩展功能