wangEditor：轻量级富文本编辑器的高效实践

2025-07-14 08:30:10

前言

在现代 Web 应用中，富文本内容的编辑与展示已成为不可或缺的一部分。无论是博客系统、内容管理系统（CMS）、在线文档协作平台，还是用户评论模块，都离不开一个稳定、灵活且易于扩展的富文本编辑器。wangEditor 是一款由国内团队开发并持续维护的开源富文本编辑器，以其轻量化、易用性、良好的中文支持和可定制能力而广受开发者欢迎。

Logo

它基于原生 JavaScript 实现，不依赖任何框架，同时也提供了对 React、Vue 等主流前端框架的良好兼容性。本文将围绕 wangEditor 的安装配置、核心功能及实际使用方法展开详细介绍，帮助开发者全面掌握这一工具的应用方式。

wangEditor 简介

wangEditor 是一个面向 Web 的富文本编辑器，采用 HTML5 和 CSS3 技术实现，具备跨浏览器兼容性和良好的移动端适配能力。其设计目标是提供一种简单直观的内容输入方式，同时保持高度的可定制性，满足从基础编辑到复杂排版的各种需求。

该编辑器内置丰富的功能模块，包括但不限于：

  • 文字格式化：加粗、斜体、下划线、删除线等
  • 段落控制：标题、列表、缩进、对齐方式
  • 插入元素：图片、视频、链接、表格、代码块
  • 颜色与字体设置
  • 撤销/重做、剪切板操作
  • 多语言支持

此外，wangEditor 提供了清晰的插件机制，开发者可以通过自定义插件来扩展编辑器的功能，实现个性化需求。

安装与初始化

wangEditor 支持多种安装方式，适用于不同的开发环境和项目结构。

使用 npm 安装

推荐使用 npm 进行安装，这是最常见也是最推荐的方式：

npm install wangeditor --save

安装完成后，在你的 JavaScript 文件中引入并初始化编辑器：

import E from 'wangeditor'

const editor = new E('#editor-container')
editor.create()

其中 #editor-container 是你页面上用于承载编辑器的 DOM 容器。

使用 CDN 引入

如果你希望快速测试或不使用模块打包工具，也可以通过 CDN 方式引入：

<script src="https://cdn.jsdelivr.net/npm/wangeditor@latest/dist/wangEditor.min.js"></script>
<div id="editor-container" style="width: 100%; height: 400px;"></div>
<script>
  const E = window.wangEditor
  const editor = new E('#editor-container')
  editor.create()
</script>

Vue 中使用

对于 Vue 项目，你可以将其封装为一个组件：

<template>
  <div>
    <div ref="editorContainer" style="width: 100%; height: 400px;"></div>
  </div>
</template>

<script>
import E from 'wangeditor'

export default {
  mounted() {
    this.editor = new E(this.$refs.editorContainer)
    this.editor.create()
  },
  beforeDestroy() {
    this.editor.destroy()
  }
}
</script>

React 中使用

在 React 项目中，可以如下方式集成：

import React, { useRef, useEffect } from 'react'
import E from 'wangeditor'

function WangEditorComponent() {
  const editorRef = useRef(null)

  useEffect(() => {
    const editor = new E(editorRef.current)
    editor.create()

    return () => {
      editor.destroy()
    }
  }, [])

  return <div ref={editorRef} style={{ width: '100%', height: '400px' }}></div>
}

export default WangEditorComponent

核心功能与使用方式

wangEditor 提供了丰富的 API 接口和配置项，开发者可以根据业务需求进行灵活调整。

初始化配置

你可以在创建编辑器时传入配置对象，以控制其行为：

const editor = new E('#editor-container')

editor.config.placeholder = '请输入内容...'
editor.config.menus = [
  'bold', 'fontSize', 'fontName', 'italic', 'underline', 'strikeThrough',
  'foreColor', 'backColor', 'link', 'list', 'justify', 'quote', 'image', 'table'
]
editor.config.uploadImgServer = '/api/upload' // 图片上传接口
editor.config.showFullScreen = true

editor.create()

上述配置项分别设置了占位符、菜单栏显示项、图片上传地址以及是否显示全屏按钮。

获取与设置内容

获取当前编辑器中的内容非常简单：

const htmlContent = editor.txt.html() // 获取 HTML 内容
const textContent = editor.txt.text() // 获取纯文本内容

你也可以动态设置内容：

editor.txt.html('<p>初始内容</p>')

图片与视频上传

wangEditor 支持本地图片上传，并可通过配置指定上传服务器地址：

editor.config.uploadImgServer = '/upload-image'
editor.config.uploadFileName = 'myFile' // 后端接收文件的字段名
editor.config.uploadImgParams = {
  token: 'your_token_here'
}

上传成功后，服务端需返回如下格式的数据：

{
  "errno": 0,
  "data": ["http://example.com/image.jpg"]
}

若需支持视频嵌入，可启用相应配置：

editor.config.letOuterVideo = true

插件机制与自定义功能

wangEditor 支持通过插件机制扩展功能。例如，你可以注册一个自定义按钮，插入特定内容：

E.registerMenu('customButton', {
  title: '插入签名',
  iconSvg: '<svg>...</svg>',
  clickHandler(editor) {
    editor.cmd.do('insertHTML', '<p>—— 此致 敬礼</p>')
  }
})

然后在菜单配置中添加该按钮：

editor.config.menus.push('customButton')

多语言支持

wangEditor 内置了英文和中文语言包，可以通过配置切换语言：

import zhCn from 'wangeditor/dist/i18nextLng/zh-CN'
import enUs from 'wangeditor/dist/i18nextLng/en-US'

editor.config.lang = zhCn

事件监听

你可以监听编辑器内部事件，如内容变化、选区变化等：

editor.config.onchange = function (newHtml) {
  console.log('内容发生变化：', newHtml)
}

editor.config.onfocus = function () {
  console.log('编辑器获得焦点')
}

安全与内容过滤

为了防止 XSS 攻击或非法标签注入，wangEditor 默认会对内容进行一定程度的清理。你也可以自定义允许的标签和属性：

editor.config.pasteIgnoreStyle = true
editor.config.styleWithCSS = false
editor.config.allowedTags = ['p', 'strong', 'em', 'ul', 'li']

主题与样式定制

虽然 wangEditor 提供了默认主题，但你也可以通过 CSS 覆盖其样式，以匹配项目整体风格。

例如，修改编辑器内的字体大小：

.w-e-text-container p {
  font-size: 16px;
}

或者更换整个编辑器的主题背景色：

.w-e-text-container {
  background-color: #f9f9f9;
}

兼容性与性能优化

wangEditor 设计之初就考虑了跨浏览器兼容性，支持主流浏览器，包括 Chrome、Firefox、Safari、Edge 及部分版本的 IE11。对于移动端，也进行了良好适配，确保在手机和平板设备上的流畅体验。

由于其轻量级架构，wangEditor 在资源占用和渲染性能方面表现优异，适合嵌入在各种类型的应用中，无论是后台管理系统还是前台用户交互界面。

总结

wangEditor 是一款轻量级、功能丰富且易于集成的富文本编辑器，凭借其简洁的 API、良好的中文支持和可扩展性，成为众多开发者构建 Web 编辑功能的首选工具。

wangeditor-team
wangeditor-team/wangEditor
wangEditor，开源Web富文本编辑器
TypeScript
MIT
18.0 k