WangEditor — 轻量级富文本编辑器的核心功能与实战应用

1. 为什么选择WangEditor作为你的富文本编辑器？

在开发内容管理系统、在线文档工具或者社区论坛时，富文本编辑器就像是一把瑞士军刀。我尝试过至少十几种编辑器，从老牌的CKEditor到新兴的Slate.js，最后发现WangEditor在轻量化和易用性上找到了完美平衡点。它的压缩后核心代码只有200KB左右，加载速度比同类产品快30%以上，这对于需要快速响应的Web应用来说简直是福音。

记得去年给一个电商平台做商品详情编辑器时，客户要求同时支持PC和手机端操作。实测下来，WangEditor的响应式设计在iPad上都能完美适配触控操作，而且不需要额外写兼容代码。它的工具栏会自动根据容器宽度调整布局，这个细节处理比很多国外编辑器都要人性化。

2. 5分钟快速上手WangEditor

2.1 两种安装方式任你选

如果你习惯传统前端开发，直接CDN引入是最快的方式。在HTML的

<link href="https://unpkg.com/@wangeditor/editor@latest/dist/css/style.css" rel="stylesheet"> <script src="https://unpkg.com/@wangeditor/editor@latest/dist/index.js"></script>

现代前端项目更推荐用npm安装。我在Vue3项目中的实际配置是这样的：

npm install @wangeditor/editor @wangeditor/editor-for-vue --save

2.2 创建一个基础编辑器

这个代码片段是我在多个项目中验证过的最佳实践：

<template> <div class="editor-wrapper"> <Toolbar :editor="editorRef" :defaultConfig="toolbarConfig"/> <Editor v-model="content" :defaultConfig="editorConfig" @onCreated="handleCreated" style="height: 400px" /> </div> </template> <script setup> import { ref, shallowRef, onBeforeUnmount } from 'vue' import { Editor, Toolbar } from '@wangeditor/editor-for-vue' const editorRef = shallowRef() const content = ref('<p>初始内容</p>') const toolbarConfig = {} const editorConfig = { placeholder: '开始输入...', MENU_CONF: { uploadImage: { server: '/api/upload' // 你的图片上传接口 } } } const handleCreated = (editor) => { editorRef.value = editor } onBeforeUnmount(() => { const editor = editorRef.value if (editor == null) return editor.destroy() }) </script>

注意：一定要记得在组件销毁时调用editor.destroy()，否则会导致内存泄漏。这是我踩过的坑，特别是在SPA应用中。

3. 深度定制你的编辑器

3.1 像搭积木一样配置菜单

WangEditor的菜单配置灵活得令人惊喜。比如要做一个简化的评论框，只需要保留粗体、斜体和表情：

const toolbarConfig = { excludeKeys: [ 'headerSelect', 'blockquote', '|', // 分隔线 'color', 'bgColor', 'fontSize', 'fontFamily', 'lineHeight', 'bulletedList', 'numberedList', 'todo', 'insertLink', 'insertTable', 'codeBlock', 'divider', 'emotion', 'insertImage', 'uploadImage', 'insertVideo', 'undo', 'redo' ] }

3.2 自定义图片上传逻辑

实际项目中，我们通常需要对接自己的文件存储服务。这是我常用的七牛云上传适配方案：

const editorConfig = { MENU_CONF: { uploadImage: { async customUpload(file, insertFn) { const formData = new FormData() formData.append('file', file) try { const res = await axios.post('/api/qiniu/upload', formData) insertFn(res.data.url, '', res.data.url) } catch (err) { console.error('上传失败', err) } } } } }

4. 性能优化实战技巧

4.1 懒加载提升首屏速度

在Next.js项目中，我这样实现编辑器的动态加载：

import dynamic from 'next/dynamic' const EditorComponent = dynamic( () => import('@wangeditor/editor-for-react').then(mod => mod.Editor), { ssr: false } ) const ToolbarComponent = dynamic( () => import('@wangeditor/editor-for-react').then(mod => mod.Toolbar), { ssr: false } )

4.2 处理大文档的渲染卡顿

当文档超过5万字时，可以启用分段渲染：

const editorConfig = { scroll: false, autoFocus: false, onCreated(editor) { // 监听滚动事件实现懒加载 editor.$textContainerElem.on('scroll', throttle(loadVisibleContent, 300)) } }

5. 与其他技术栈的集成

5.1 在React中避免重复渲染

使用useMemo优化编辑器实例：

function RichTextEditor() { const [editor, setEditor] = useState(null) const toolbarConfig = useMemo(() => ({}), []) const editorConfig = useMemo(() => ({ placeholder: '输入内容...' }), []) return ( <> <Toolbar editor={editor} defaultConfig={toolbarConfig}/> <Editor defaultConfig={editorConfig} onCreated={setEditor} style={{ height: '500px' }} /> </> ) }

5.2 与Markdown互转

虽然WangEditor原生不支持Markdown，但可以通过插件实现：

import { markdownToHtml, htmlToMarkdown } from 'wangEditor-plugin-markdown' // 初始化时注册插件 editorConfig.MENU_CONF.markdown = { markdownToHtml, htmlToMarkdown }

6. 企业级项目中的最佳实践

在最近一个OA系统项目中，我们遇到了协同编辑的需求。虽然WangEditor本身不直接支持OT算法，但可以通过监听变化事件实现基础协作：

editor.on('change', debounce(() => { const content = editor.getHtml() socket.emit('editor-update', { docId: currentDocId, content }) }, 500)) socket.on('remote-update', (content) => { editor.setHtml(content) })

对于需要版本历史的功能，可以结合Delta格式进行优化：

import { htmlToDelta, deltaToHtml } from 'wangEditor-delta' const delta = htmlToDelta(editor.getHtml()) saveVersionToDatabase(delta) // 恢复版本时 const delta = loadFromDatabase() editor.setHtml(deltaToHtml(delta))

7. 常见问题排查指南

7.1 样式冲突解决方案

当编辑器样式被全局CSS污染时，可以这样隔离：

.editor-container { all: initial; * { all: unset; } /* 重新引入编辑器样式 */ @import '@wangeditor/editor/dist/css/style.css'; }

7.2 移动端输入法兼容问题

在Android微信浏览器中，可能会遇到输入法遮挡问题。这个修复方案很管用：

editorConfig.onFocus() { setTimeout(() => { const editable = editor.$textElem.elems[0] editable.scrollIntoView({ block: 'center' }) }, 300) }

8. 插件开发进阶

创建一个简单的字数统计插件：

class WordCountPlugin { constructor(editor) { this.editor = editor this.$elem = $(`<div class="word-count">0字</div>`) editor.on('change', this.updateCount.bind(this)) } updateCount() { const text = this.editor.getText() this.$elem.text(`${text.length}字`) } } // 注册插件 window.wangEditor.plugins.wordCount = WordCountPlugin // 使用插件 editorConfig.plugins = ['wordCount']