10分钟上手Tiptap：打造属于你的现代富文本编辑器

10分钟上手Tiptap：打造属于你的现代富文本编辑器

【免费下载链接】tiptap 项目地址: https://gitcode.com/gh_mirrors/tip/tiptap

你还在为寻找一款轻量、灵活且功能强大的富文本编辑器而烦恼吗？Tiptap作为一款基于ProseMirror的无头编辑器框架，让你无需从零构建，就能快速实现自定义编辑器。本文将带你在10分钟内完成从环境搭建到功能扩展的全流程，读完你将掌握：基础安装配置、核心API使用、常用扩展集成以及Vue3环境下的实战应用。

什么是Tiptap

Tiptap是一个基于ProseMirror的无头（headless）富文本编辑器框架。与传统编辑器不同，它不提供预设UI，而是通过模块化设计让开发者完全掌控编辑器的外观和行为。其核心优势在于：

• 高度可定制：从工具栏到内容渲染，所有组件均可自定义
• 模块化扩展：通过官方扩展包轻松添加功能，如extension-bold（加粗）、extension-link（链接）等
• 多框架支持：提供vue-3、react等框架集成方案
• 企业级稳定性：已被知名机构采用

快速开始：基础环境搭建

安装核心依赖

通过npm安装Tiptap核心包及Vue3适配器：

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

基础编辑器实现

创建一个最简化的Vue组件，实现基础编辑功能：

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

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

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

这段代码通过StarterKit快速集成了基础编辑功能，包括段落、标题、列表等常用格式。

核心概念解析

编辑器实例

useEditor钩子创建的编辑器实例是交互核心，提供丰富API：

// 获取当前内容
editor.getHTML() 
// 设置内容
editor.commands.setContent('<p>新内容</p>')
// 执行命令
editor.commands.bold().exec()

完整API文档可参考core包文档。

扩展系统

Tiptap通过扩展实现功能扩展，官方提供40+扩展包，如：

扩展类型	包路径	功能描述
格式化	extension-bold	文本加粗
结构	extension-table	表格支持
媒体	extension-image	图片插入
协作	extension-collaboration	多人协作

添加扩展只需在配置中引入：

import Bold from '@tiptap/extension-bold'

const editor = useEditor({
  extensions: [
    StarterKit,
    Bold // 添加加粗功能
  ]
})

功能扩展：打造实用编辑器

自定义工具栏

结合Vue组件实现简单工具栏：

<template>
  <div>
    <button @click="editor.chain().focus().bold().run()" :class="{ active: editor.isActive('bold') }">
      加粗
    </button>
    <editor-content :editor="editor" />
  </div>
</template>

使用editor.isActive('bold')判断当前选中内容是否为粗体，实现工具栏状态同步。

高级功能集成

1. 代码块高亮

通过extension-code-block-lowlight实现语法高亮：

import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight'
import { lowlight } from 'lowlight/lib/core'
import javascript from 'lowlight/lib/languages/javascript'

lowlight.registerLanguage('javascript', javascript)

// 在编辑器配置中添加
extensions: [
  StarterKit,
  CodeBlockLowlight.configure({
    lowlight
  })
]

2. 协作编辑

extension-collaboration提供多人实时协作能力：

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

const ydoc = new Y.Doc()
const provider = new WebrtcProvider('tiptap-collab-room', ydoc)
const yXmlFragment = ydoc.getXmlFragment('document')

// 编辑器配置
extensions: [
  Collaboration.configure({
    document: ydoc,
    fragment: yXmlFragment
  })
]

实战案例：内容管理系统编辑器

完整组件实现

<template>
  <div class="editor-container">
    <!-- 工具栏 -->
    <div class="toolbar">
      <button @click="toggleBold">加粗</button>
      <button @click="toggleLink">链接</button>
      <button @click="insertImage">图片</button>
    </div>
    <!-- 编辑区域 -->
    <editor-content :editor="editor" />
  </div>
</template>

<script setup>
import { useEditor, EditorContent } from '@tiptap/vue-3'
import StarterKit from '@tiptap/starter-kit'
import Link from '@tiptap/extension-link'
import Image from '@tiptap/extension-image'

const editor = useEditor({
  extensions: [
    StarterKit,
    Link.configure({ openOnClick: true }),
    Image.configure({
      allowBase64: true
    })
  ],
  content: '<p>开始编辑你的内容吧...</p>'
})

// 工具栏命令
const toggleBold = () => editor.chain().focus().toggleBold().run()
const toggleLink = () => {
  const url = prompt('请输入链接:')
  if (url) editor.chain().focus().toggleLink({ href: url }).run()
}
const insertImage = () => {
  const src = prompt('请输入图片URL:')
  if (src) editor.chain().focus().setImage({ src }).run()
}
</script>

<style scoped>
.editor-container {
  border: 1px solid #ccc;
  border-radius: 4px;
}
.toolbar {
  padding: 8px;
  border-bottom: 1px solid #ccc;
}
button {
  margin-right: 8px;
  padding: 4px 8px;
}
</style>

关键功能解析

1. 链接功能：通过extension-link实现，支持自定义链接行为
2. 图片处理：extension-image支持Base64和远程图片
3. 命令链：使用editor.chain()串联多个编辑操作，如focus().toggleBold().run()

扩展学习资源

• 官方文档：docs/api/utilities.md提供工具函数详细说明
• 示例代码：demos/src/Examples/包含丰富使用场景
• 社区教程：README.md提供项目概述和贡献指南

总结与进阶方向

通过本文你已掌握Tiptap的基础使用，如需进一步提升可探索：

1. 自定义节点：通过ProseMirror API创建自定义内容类型，如公式、图表
2. 性能优化：针对大文档场景优化渲染性能
3. 移动端适配：结合触摸事件优化移动体验
4. 全功能集成：参考demos/src/Demos/实现企业级编辑器

立即访问项目仓库获取完整代码，开始构建你的专属编辑器吧！

【免费下载链接】tiptap 项目地址: https://gitcode.com/gh_mirrors/tip/tiptap