革命性富文本编辑工具Tiptap：从入门到精通的实战教程

你还在为富文本编辑器的兼容性和定制化烦恼吗？Tiptap作为一款无头(Headless)、框架无关的富文本编辑工具，正通过其独特的扩展系统和设计自由度改变这一现状。本文将带你从核心概念到实战应用，全面掌握这款被《纽约时报》《卫报》等知名企业采用的编辑器框架。读完本文你将获得：

• 3分钟搭建基础编辑器的快速上手指南
• 10+常用扩展的配置与组合技巧
• 协作编辑功能的无缝集成方案
• 从JSON到HTML的内容转换全流程

认识Tiptap：重新定义富文本编辑

Tiptap的核心优势在于其无头架构（无预设UI）和扩展系统。与传统编辑器不同，它不捆绑任何样式，让开发者拥有100%的设计控制权。这种架构使其能够无缝集成到Vue、React或纯JavaScript项目中，同时保持轻量级特性。

官方定义中提到："Tiptap是基于ProseMirror构建的开发者组件集合，形成了高级付费功能的基础"。其模块化设计体现在packages/目录结构中，每个功能都被拆分为独立包，如核心模块packages/core/和基础扩展集packages/starter-kit/。

核心特性解析

• 框架无关性：通过packages/react/、packages/vue-3/等适配器支持多框架
• 扩展生态：100+官方与社区扩展，从基础格式化packages/extension-bold/到高级协作packages/extension-collaboration/
• 内容处理：提供HTML与JSON双向转换能力，详见docs/api/utilities.md
• 协作编辑：基于Yjs的实时协作支持，配合Hocuspocus后端实现多人同时编辑

快速上手：3分钟搭建你的第一个编辑器

基础安装与配置

通过npm安装核心包和基础扩展集：

npm install @tiptap/core @tiptap/starter-kit

创建基础编辑器实例（JavaScript版）：

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'

new Editor({
  element: document.querySelector('#editor'),
  extensions: [
    StarterKit.configure({
      bold: true,
      italic: true,
      // 按需启用扩展
    }),
  ],
  content: '<p>Hello Tiptap!</p>',
})

框架集成示例

React集成（demos/setup/react.ts）：

import { EditorContent, useEditor } from '@tiptap/react'

export default function MyEditor() {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello React Tiptap!</p>',
  })

  return <EditorContent editor={editor} />
}

Vue3集成（demos/setup/vue.ts）：

<template>
  <editor-content :editor="editor" />
</template>

<script>
import { useEditor } from '@tiptap/vue-3'
import StarterKit from '@tiptap/starter-kit'

export default {
  setup() {
    const editor = useEditor({
      extensions: [StarterKit],
      content: '<p>Hello Vue Tiptap!</p>',
    })
    return { editor }
  },
}
</script>

扩展系统实战：打造专属编辑器

Tiptap的灵魂在于其扩展系统。每个功能（如表格、图片、代码块）都是独立扩展，可按需组合。以下是实战场景中的扩展配置方案：

基础格式化扩展组合

import StarterKit from '@tiptap/starter-kit'
import CodeBlock from '@tiptap/extension-code-block'
import Table from '@tiptap/extension-table'
import TableRow from '@tiptap/extension-table-row'
import TableCell from '@tiptap/extension-table-cell'
import TableHeader from '@tiptap/extension-table-header'

// 组合基础编辑功能
const BasicExtensions = [
  StarterKit.configure({
    heading: {
      levels: [1, 2, 3] // 仅启用h1-h3
    },
    codeBlock: false // 禁用默认代码块，使用高级版
  }),
  CodeBlock.configure({
    languageClassPrefix: 'language-'
  }),
  Table.configure({
    resizable: true // 启用表格拖拽调整
  }),
  TableRow,
  TableHeader,
  TableCell
]

高级功能配置

图片上传（packages/extension-image/）：

import Image from '@tiptap/extension-image'

Image.configure({
  allowBase64: true,
  uploadDir: '/uploads',
  async onUpload(file) {
    // 自定义上传逻辑
    const formData = new FormData()
    formData.append('image', file)
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData
    })
    return { url: await response.json() }
  }
})

协作编辑（demos/src/Demos/SingleRoomCollab/）：

import Collaboration from '@tiptap/extension-collaboration'
import * as Y from 'yjs'
import { WebrtcProvider } from 'y-webrtc'

// 创建共享文档
const doc = new Y.Doc()
const provider = new WebrtcProvider('unique-room-id', doc)
const yXmlFragment = doc.getXmlFragment('document')

new Editor({
  extensions: [
    StarterKit,
    Collaboration.configure({
      document: doc,
      fragment: yXmlFragment
    })
  ],
  content: '<p>开始协作编辑...</p>'
})

内容处理：从JSON到HTML的全流程

Tiptap采用JSON作为内容存储格式，提供灵活的内容操作能力。以下是典型的内容生命周期管理：

内容导出与导入

// 获取编辑器内容（JSON格式）
const jsonContent = editor.getJSON()

// 从JSON加载内容
editor.commands.setContent(jsonContent)

// 直接渲染JSON为HTML（无需编辑器实例）
import { generateHTML } from '@tiptap/html'

const html = generateHTML(jsonContent, [StarterKit])

实用工具

文档转换工具在docs/api/utilities.md中有详细说明，包括：

• JSON↔HTML双向转换
• PHP集成方案
• 提及(Mentions)与表情建议功能

实战案例：构建Notion风格编辑器

通过组合块级扩展和自定义节点，可构建类Notion编辑器。关键实现包括：

1. 使用packages/extension-list-item/和packages/extension-paragraph/创建块基础
2. 集成packages/extension-mention/实现@提及功能
3. 自定义节点视图实现块操作菜单

核心代码结构（参考demos/src/Demos/）：

import { Node } from '@tiptap/core'

const CustomBlock = Node.create({
  name: 'customBlock',
  group: 'block',
  content: 'inline*',
  parseHTML() {
    return [{ tag: 'div[data-type="custom-block"]' }]
  },
  renderHTML({ HTMLAttributes }) {
    return ['div', { ...HTMLAttributes, 'data-type': 'custom-block' }, 0]
  }
})

高级应用：协作编辑与实时同步

Tiptap的协作功能基于Yjs实现，通过packages/extension-collaboration-cursor/提供用户光标显示。完整实现需要：

1. 安装协作扩展：npm install @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor yjs y-webrtc
2. 配置Hocuspocus后端服务
3. 实现用户存在状态管理

示例架构图：

graph TD
    A[客户端A] -->|WebRTC| B[Hocuspocus服务器]
    C[客户端B] -->|WebRTC| B
    B --> D[(共享文档)]
    A --> E[本地编辑器实例]
    C --> F[本地编辑器实例]
    E --> G[光标同步]
    F --> G

总结与进阶资源

Tiptap通过其模块化设计和扩展系统，重新定义了富文本编辑的开发体验。从基础文本编辑到企业级协作系统，其灵活性满足了各种场景需求。官方提供了丰富的学习资源：

• 示例项目：demos/目录包含50+使用场景
• API文档：docs/api/提供完整接口说明
• 社区扩展：Awesome Tiptap集合了100+第三方扩展

进阶学习路径建议：

1. 掌握自定义扩展开发（参考CONTRIBUTING.md）
2. 深入ProseMirror核心概念
3. 探索Tiptap Cloud的高级功能

通过本文介绍的方法，你可以快速构建功能完善的富文本编辑解决方案，同时保持代码的可维护性和扩展性。立即访问官方仓库开始尝试，或查看demos/index.html在线示例。

提示：遇到问题可通过Discuss Tiptap on GitHub获取社区支持，贡献代码请遵循CONTRIBUTING.md指南。