50 行代码 Vue3 中使用 wangEditor 富文本编辑器

更新

wangEditor V5 已正式发布，查看官网。

前言

本文使用 wangEditor V5 实现 Vue3 编辑器。wangEditor V5 官方提供 Vue 组件，使用非常简单。

wangEditor V5 正在公开测试中，有问题和建议可以提交到 github issue 。

【注意】编辑器后续可能继续升级，API 和配置或许会调整。所以问题请及时查阅文档，不要仅依赖本文。

安装

使用 vue-cli 初始化一个 Vue3 环境，然后安装

yarn add @wangeditor/editor @wangeditor/editor-for-vue@next

创建编辑器

写代码

定义一个组件 MyEditor.vue ，代码如下。约 50 行，逻辑也很简单。（源代码在文章最后）

<script setup>
import { onBeforeUnmount, ref, shallowRef, onMounted } from 'vue'
import { Editor, Toolbar } from '@wangeditor/editor-for-vue'

// 编辑器实例，必须用 shallowRef，重要！
const editorRef = shallowRef()

// 内容 HTML
const valueHtml = ref('<p>hello</p>')

// 模拟 ajax 异步获取内容
onMounted(() => {
    setTimeout(() => {
        valueHtml.value = '<p>模拟 Ajax 异步设置内容</p>'
    }, 1500)
})

// 编辑器配置
const editorConfig = {
    placeholder: '请输入内容...',
    MENU_CONF: { /* 菜单配置，下文解释 */ }
}

const handleCreated = (editor) => {
    editorRef.value = editor // 记录 editor 实例，重要！
}

// 组件销毁时，及时销毁编辑器
onBeforeUnmount(() => {
    const editor = editorRef.value
    if (editor == null) return
    editor.destroy()
})
</script>

<template>
    <div style="border: 1px solid #ccc">
        <!-- 工具栏 -->
        <Toolbar
            :editor="editorRef"
            :defaultConfig="toolbarConfig"
            style="border-bottom: 1px solid #ccc"
        />
        <!-- 编辑器 -->
        <Editor
            v-model="valueHtml"
            :defaultConfig="editorConfig"
            style="height: 500px; overflow-y: hidden;"
            @onCreated="handleCreated"
        />
    </div>
</template>

<!-- 别忘了引入样式 -->
<style src="@wangeditor/editor/dist/css/style.css"></style>

运行

把 MyEditor.vue 引入到 App.vue 中，即可生成一个功能齐全的编辑器。内容变化时会同步到 valueHtml 。

注意事项

• 定义 editorRef 时要使用 shallowRef
• Vue 组件销毁时，及时销毁编辑器

配置

编辑器配置

上文代码中只配置了 placeholder作为示例。它还支持 readOnly autoFocus maxLength 等配置，可参考文档。

// 编辑器配置
const editorConfig = {
    placeholder: '请输入内容...',
    // 可继续其他配置...
    
    MENU_CONF: { /* 菜单配置，下文解释 */ }
}

但请注意，该文档中的所有回调函数，都不能以配置的形式传入，如 onCreated onChange onDestroyed 等。这些回调函数必须以 Vue 事件的方式传入。

<Editor
    :editorId="editorId"
    :defaultConfig="editorConfig"
    :defaultContent="defaultContent"
    :defaultHtml="defaultHtml"
    style="height: 500px"
    
    <!-- 回调函数，以 Vue 事件形式 -->
    @onCreated="handleCreated"
    @onChange="handleChange"
    @onDestroyed="handleDestroyed"
    @onFocus="handleFocus"
    @onBlur="handleBlur"
    @customAlert="customAlert"
    @customPaste="customPaste"
  />

工具栏配置

如果你想修改工具栏的菜单，如隐藏某些菜单，重新排序分组，就可以使用该配置。支持 toolbarKeys 和 excludeKeys，可参考文档。

// 工具栏配置
const toolbarConfig = {
    toolbarKeys: [ /* 显示哪些菜单，如何排序、分组 */ ],
    excludeKeys: [ /* 隐藏哪些菜单 */ ],
}

<Toolbar
    :editorId="editorId"
    :defaultConfig="toolbarConfig" <!-- 传入配置 -->
    style="border-bottom: 1px solid #ccc"
/>

菜单配置

如果你想对某个菜单进行配置，例如配置颜色、字体、字号，配置上传图片的 API 地址等，可以使用菜单配置。具体参考文档。

// 编辑器配置
const editorConfig = {
    // 某些编辑器配置，如 placeholder
    
    // 所有的菜单配置，都要在 MENU_CONF 属性下
    MENU_CONF: {
        // 配置字号
        fontSize: [ ... ],
        
        // 配置上传图片
        uploadImage: { ... },
        
        // 继续其他菜单配置
    }
}

API

wangEditor 提供了丰富的 API ，可以帮助你进行任何编辑器操作。可参考文档。

• 配置相关的 API
• 内容处理相关的 API
• 节点操作相关的 API
• 选区操作相关的 API
• 自定义事件的 API

在编辑器创建完成之后，可以通过 editorRef.value 获取 editor 实例，然后执行 API 。

onBeforeUnmount(() => {
    const editor = editorRef.value // 获取 editor 实例
    if (editor == null) return

    editor.destroy() // 执行 API
})

总结

本文所有源代码在这里。

wangEditor V5 正在公开测试中，有问题和建议可以提交到 github issue 。