tiptap

Tiptap 富文本编辑器

概览

Tiptap 是一款基于 ProseMirror 构建的无头富文本编辑器，为 React 应用提供模块化扩展系统。它支持 React 19、Tailwind v4，以及 Next.js 等 SSR 框架。适用于构建博客编辑器、评论系统、文档工具或类似 Notion 的协作应用。请勿与 Create React App 一起使用（CRA 与 Tiptap v3 的 ESM 模块结构不兼容；请改用 Vite）。

快速参考

模式	API / 要点
创建编辑器	useEditor({ extensions: [StarterKit], immediatelyRender: false })
渲染编辑器	<EditorContent editor={editor} />
Prose 样式	在容器中添加 className="prose dark:prose-invert max-w-none"
配置 StarterKit	StarterKit.configure({ heading: { levels: [1, 2, 3] } })
禁用撤销/重做	StarterKit.configure({ undoRedo: false })（Y.js 协作所必需）
图片上传	设置 allowBase64: false，使用上传处理程序替换 URL
Markdown 支持	import { Markdown } from '@tiptap/markdown'（官方开源）
shadcn 组件	npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json
空值检查	useEditor() 返回 Editor | null — 调用方法前先进行检查

核心依赖项

包	用途
@tiptap/react	React 集成（自 v2.10.0 起支持 React 19）
@tiptap/starter-kit	捆绑扩展：标记、节点和功能
@tiptap/pm	ProseMirror 对等依赖项（必需，不会自动安装）
@tailwindcss/typography	用于标题、列表和链接的 Prose 样式

StarterKit v3 包含内容

类别	包含内容
标记	粗体、斜体、删除线、代码、链接（v3）、下划线（v3）
节点	文档、段落、文本、标题、项目符号列表、有序列表、列表项、引用块、代码块、水平线、硬换行
功能	撤销/重做、Dropcursor、Gapcursor、ListKeymap（v3）、TrailingNode（v3）

常用附加扩展

扩展	包	使用场景
Image	@tiptap/extension-image	支持调整大小的图像
Color	@tiptap/extension-color	文本颜色（需要 TextStyle）
Typography	@tiptap/extension-typography	智能引号、破折号、省略号
Placeholder	@tiptap/extension-placeholder	占位文本（需要 CSS）
Table	@tiptap/extension-table	表格支持（以及 Row、Cell、Header）
TaskList	@tiptap/extension-task-list	复选框任务列表
CodeBlockLowlight	@tiptap/extension-code-block-lowlight	语法高亮代码
Collaboration	@tiptap/extension-collaboration	多用户实时协作编辑（Y.js）
Markdown	@tiptap/markdown	双向 Markdown（开源）

常见错误

错误	修正
缺少 immediatelyRender: false	将其添加到 useEditor() 配置中——SSR/Next.js 必需
编辑器容器缺少 prose 类	添加 className="prose prose-sm dark:prose-invert max-w-none"
图像以 base64 格式存储	设置 allowBase64: false，使用上传处理程序通过 URL 替换
同时使用 EditorProvider 和 useEditor	二选一——EditorProvider 内部会封装 useEditor
启用 Collaboration 时启用 Undo/Redo	使用 Y.js 时，在 StarterKit 中设置 undoRedo: false
ProseMirror 版本冲突	在 package.json 中为 prosemirror-model/view/state 添加 resolutions
使用 Create React App	切换到 Vite——CRA 与 v3 ESM 模块不兼容
未检查 editor 是否为 null	useEditor() 返回 Editor | null——使用前进行保护
协作时使用 history: false	v3 中配置键已重命名为 undoRedo
导入 @tiptap/extension-markdown	正确的包是 @tiptap/markdown

委派

• Tailwind 样式：参阅 tailwind 技能
• 表单集成：参阅 tanstack-form 技能

参考资料

• 设置与配置
• 扩展目录
• 图像上传
• 模式
• 已知问题与错误
• Prose 样式