Quill富文本编辑器实战：5分钟搞定Vue3集成与自定义图片上传

Vue3 + Quill 富文本编辑器：从零到一构建企业级内容编辑体验

如果你正在为Vue3项目寻找一个既轻量又强大的富文本编辑器，那么Quill很可能就是你一直在找的答案。我在最近的一个企业级内容管理系统中深度集成了Quill，整个过程虽然遇到了一些挑战，但最终的效果让我相当满意。Quill的模块化设计让它能够轻松适应各种复杂的业务场景，而Vue3的Composition API又为这种集成提供了天然的便利。

这篇文章不会只是简单重复官方文档的内容，而是会分享我在实际项目中踩过的坑、总结的最佳实践，以及一些你可能在其他地方找不到的实用技巧。无论你是要构建博客后台、电商商品详情编辑器，还是企业内部的知识管理系统，这里的内容都能帮你节省大量摸索时间。

1. 为什么选择Quill？深入对比主流富文本编辑器

在开始技术实现之前，我们先花点时间搞清楚为什么Quill值得选择。市面上富文本编辑器不少，每个都有自己的特色和适用场景。

1.1 主流编辑器横向对比

我在选型阶段详细对比了多个主流编辑器，下面这个表格总结了关键差异：

Quill最吸引我的地方在于它的模块化架构。你可以把它想象成一个乐高积木系统——基础版本只提供最核心的编辑功能，但你可以通过添加各种模块来扩展能力。这种设计让Quill既保持了核心的轻量，又具备了无限的扩展可能性。

1.2 Quill的核心设计哲学

Quill的设计有几个关键特点值得深入了解：

Delta数据模型是Quill的灵魂。与传统的HTML字符串存储不同，Quill使用JSON格式的Delta来描述内容变化。这种设计带来了几个好处：

// 一个简单的Delta示例
{
\”ops\”: [
{ \”insert\”: \”Hello \” },
{ \”insert\”: \”World\”, \”attributes\”: { \”bold\”: true } },
{ \”insert\”: \”\\n\” }
]
}

这种数据格式让内容操作变得可预测和可追溯。你可以轻松实现撤销/重做、协同编辑、内容差异比较等高级功能。在实际项目中，我经常用Delta来实现内容版本管理，每次编辑都保存一个Delta快照，这样用户就能清晰地看到内容是如何演变的。

Parchment抽象层是Quill的另一个精妙设计。它相当于在DOM之上构建了一个抽象层，让Quill能够以一致的方式处理不同浏览器和平台的差异。这意味着你不需要担心跨浏览器兼容性问题——Quill已经帮你处理好了。

提示：虽然Delta数据模型很强大，但在实际存储时，你可能需要同时保存HTML格式（用于快速渲染）和Delta格式（用于高级操作）。我在项目中通常会建立这样的数据结构：

interface ArticleContent {
html: string; // 用于前端展示
delta: any; // 用于编辑操作
rawText: string; // 用于搜索
}

2. Vue3环境下的Quill集成策略

现在让我们进入实战环节。在Vue3中集成Quill，你有几种不同的选择，每种都有各自的优缺点。

2.1 方案选择：原生Quill vs 封装库

方案一：直接使用原生Quill

// 直接安装和使用
npm install quill

方案二：使用vue-quill-editor

// Vue3专用封装
npm install @vueup/vue-quill-editor

方案三：使用Fluent Editor（基于Quill 2.0）

// 功能更丰富的封装
npm install @opentiny/fluent-editor

我个人的经验是：如果你的项目对编辑器有深度定制需求，或者你希望完全掌控编辑器的行为，那么直接使用原生Quill是最好的选择。虽然初期配置会稍微复杂一些，但长期来看，这种方案提供了最大的灵活性。

如果你需要快速上线，且功能需求相对标准，那么@vueup/vue-quill-editor是个不错的选择。它是目前Vue3生态中最活跃的Quill封装库，提供了良好的TypeScript支持。

至于Fluent Editor，它是基于Quill 2.0构建的，增加了很多实用功能（如表格、附件上传、@提醒等）。如果你的项目需要这些高级功能，可以考虑直接使用它，避免重复造轮子。

2.2 原生Quill在Vue3中的完整集成

让我们从最基础的开始。首先创建一个QuillEditor组件：

<!– QuillEditor.vue –>
<template>
<div class=\”editor-container\”>
<div ref=\”editorRef\”></div>
</div>
</template>

<script setup lang=\”ts\”>
import { ref, onMounted, onBeforeUnmount, watch } from \’vue\’
import Quill from \’quill\’
import \’quill/dist/quill.snow.css\’

interface Props {
modelValue: string
options?: any
}

const props = withDefaults(defineProps<Props>(), {
modelValue: \’\’,
options: () => ({})
})

const emit = defineEmits<{
\’update:modelValue\’: [value: string]
\’change\’: [content: string, delta: any, source: string]
}>()

const editorRef = ref<HTMLElement>()
let quillInstance: Quill | null = null

// 默认配置
const defaultOptions = {
theme: \’snow\’,
placeholder: \’请输入内容…\’,
modules: {
toolbar: [
[\’bold\’, \’italic\’, \’underline\’, \’strike\’],
[\’blockquote\’, \’code-block\’],
[{ \’header\’: 1 }, { \’header\’: 2 }],
[{ \’list\’: \’ordered\’ }, { \’list\’: \’bullet\’ }],
[{ \’script\’: \’sub\’ }, { \’script\’: \’super\’ }],
[{ \’indent\’: \’-1\’ }, { \’indent\’: \’+1\’ }],
[{ \’direction\’: \’rtl\’ }],
[{ \’size\’: [\’small\’, false, \’large\’, \’huge\’] }],
[{ \’header\’: [1, 2, 3, 4, 5, 6, false] }],
[{ \’color\’: [] }, { \’background\’: [] }],
[{ \’font\’: [] }],
[{ \’align\’: [] }],
[\’clean\’],
[\’link\’, \’image\’, \’video\’]
]
}
}

const initEditor = () => {
if (!editorRef.value) return

const options = { …defaultOptions, …props.options }
quillInstance = new Quill(editorRef.value, options)

// 设置初始内容
if (props.modelValue) {
quillInstance.clipboard.dangerouslyPasteHTML(props.modelValue)
}

// 监听内容变化
quillInstance.on(\’text-change\’, (delta, oldDelta, source) => {
if (source === \’user\’) {
const html = quillInstance?.root.innerHTML || \’\’
emit(\’update:modelValue\’, html)
emit(\’change\’, html, delta, source)
}
})
}

onMounted(() => {
initEditor()
})

onBeforeUnmount(() => {
if (quillInstance) {
quillInstance.off(\’text-change\’)
}
})

// 监听外部内容变化
watch(() => props.modelValue, (newValue) => {
if (quillInstance && newValue !== quillInstance.root.innerHTML) {
const selection = quillInstance.getSelection()
quillInstance.clipboard.dangerouslyPasteHTML(newValue)
if (selection) {
quillInstance.setSelection(selection)
}
}
})
</script>

<style scoped>
.editor-container {
height: 400px;
}

:deep(.ql-container) {
font-family: inherit;
font-size: 16px;
height: calc(100% – 42px);
}

:deep(.ql-editor) {
min-height: 300px;
}
</style>

这个基础组件已经具备了双向数据绑定、内容变化监听等核心功能。但真正的挑战才刚刚开始。

3. 深度定制：图片上传的完整解决方案

图片上传是富文本编辑器中最常见也最复杂的需求之一。Quill默认的图片处理很简单——直接插入图片URL。但在实际项目中，我们通常需要实现完整的图片上传流程。

3.1 自定义图片处理器

让我们创建一个功能完整的图片上传处理器：

// image-handler.ts
import type Quill from \’quill\’

export interface UploadResult {
url: string
width?: number
height?: number
alt?: string
}

export interface ImageHandlerOptions {
upload: (file: File) => Promise<UploadResult>
accept?: string
maxSize?: number // 单位：MB
onError?: (error: Error) => void
onProgress?: (progress: number) => void
}

export class ImageHandler {
private quill: Quill
private options: Required<ImageHandlerOptions>
private input: HTMLInputElement | null = null

constructor(quill: Quill, options: ImageHandlerOptions) {
this.quill = quill
this.options = {
accept: \’image/*\’,
maxSize: 10,
onError: () => {},
onProgress: () => {},
…options
}

this.init()
}

private init() {
// 获取工具栏模块
const toolbar = this.quill.getModule(\’toolbar\’)

// 重写图片处理器
toolbar.addHandler(\’image\’, () => {
this.handleImageClick()
})
}

private handleImageClick() {
if (!this.input) {
this.input = document.createElement(\’input\’)
this.input.type = \’file\’
this.input.accept = this.options.accept
this.input.multiple = false
this.input.style.display = \’none\’
document.body.appendChild(this.input)

this.input.addEventListener(\’change\’, this.handleFileSelect.bind(this))
}

this.input.click()
}

private async handleFileSelect(event: Event) {
const input = event.target as HTMLInputElement
const file = input.files?.[0]

if (!file) return

// 验证文件大小
if (this.options.maxSize && file.size > this.options.maxSize * 1024 * 1024) {
this.options.onError(new Error(`图片大小不能超过${this.options.maxSize}MB`))
return
}

// 验证文件类型
if (!this.validateFileType(file)) {
this.options.onError(new Error(\’不支持的文件类型\’))
return
}

try {
// 保存当前选区
const range = this.quill.getSelection()
const index = range?.index || this.quill.getLength()

// 插入占位符
this.quill.insertEmbed(index, \’image\’, {
url: \’data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAwIiBoZWlnaHQ9IjEwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMTAwIiBoZWlnaHQ9IjEwMCIgZmlsbD0iI2YwZjBmMCIvPjx0ZXh0IHg9IjUwIiB5PSI1MCIgZm9udC1mYW1pbHk9IkFyaWFsIiBmb250LXNpemU9IjEyIiBmaWxsPSIjOTk5IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkeT0iLjNlbSI+dXBsb2FkaW5nLi4uPC90ZXh0Pjwvc3ZnPg==\’,
alt: \’上传中…\’
})

// 上传文件
this.options.onProgress(0)
const result = await this.options.upload(file)
this.options.onProgress(100)

// 替换占位符为实际图片
this.quill.deleteText(index, 1)
this.quill.insertEmbed(index, \’image\’, {
url: result.url,
width: result.width,
height: result.height,
alt: result.alt || file.name
})

// 移动光标到图片后
this.quill.setSelection(index + 1, 0)

} catch (error) {
this.options.onError(error as Error)
// 删除占位符
const range = this.quill.getSelection()
if (range) {
this.quill.deleteText(range.index, 1)
}
} finally {
// 重置input
if (this.input) {
this.input.value = \’\’
}
}
}

private validateFileType(file: File): boolean {
const acceptTypes = this.options.accept.split(\’,\’).map(type => type.trim())

if (acceptTypes.includes(\’image/*\’)) {
return file.type.startsWith(\’image/\’)
}

return acceptTypes.some(type => {