在antd项目中使用wangEditor经验
我最近在前端项目中要用到富文本编辑器，找来找去发现wangEditor很不错，目前已经迭代到v5版本，WangEditor官方手册是纯中文文档，内容比较详细，非常值得推荐使用。
我使用react开发，但官方手册对react开发者写的手册不够详尽，在使用过程中还是折腾了不少时间，其中多次提交issue叨唠开发者，项目开发者王福朋都不厌其烦地帮我解决了，非常感谢。在此我写一篇在antd中使用wangEditro开发手册致敬王福朋先生，支持开源项目。
安装
yarn add @wangeditor/editor-for-react
yarn add @wangeditor/editor
基本使用
官方文档里有示例代码，但是有一些问题，按我的改一下，ide不会提示飘红，对typescript支持更好。
import React, { useState, useEffect } from 'react'
import '@wangeditor/editor/dist/css/style.css'
import { Editor, Toolbar } from '@wangeditor/editor-for-react'
import type { IDomEditor } from '@wangeditor/editor'; // 引入类型
function MyEditor() {
const [editor, setEditor] = useState<IDomEditor | null>(null) // 存储 editor 实例，指定editor的类型
// `defaultContent` (JSON 格式) 和 `defaultHtml` (HTML 格式) 二选一
// const defaultContent = [
// { type: "paragraph", children: [{ text: "一行文字" }], }
// ]
const defaultHtml = '一行文字
'
const toolbarConfig = { }
const editorConfig = {
placeholder: '请输入内容...',
onCreated(editor) { setEditor(editor) } // 记录下 editor 实例，重要！
}
// 及时销毁editor，防止内存泄露，重要！
useEffect(() => {
return () => {
if (editor == null) return
editor.destroy()
setEditor(null)
}
}, [editor])
return (
<>
<div style={{ border: '1px solid #ccc', zIndex: 100}}>
<Toolbar
editor={editor}
defaultConfig={toolbarConfig}
mode="default"
style={{ borderBottom: '1px solid #ccc' }}
/>
<Editor
defaultConfig={editorConfig}
// defaultContent={defaultContent}
defaultHtml={defaultHtml}
mode="default"
style={{ height: '500px', overflowY: 'hidden' }}
/>
</div>
</>
)
}
export default MyEditor
同步设置内容
官方手册里写了异步设置内容的方法，但我觉得实际使用中同步设置内容场景更多。应该将编辑器组件封装成功能单一的编辑器，请求数据应该安排其它组件(如dva发起请求)来完成。
同步设置内容分3块：
自定义编辑器函数头
将WangEditor进行封装，更方便使用，首先定义自定义编辑器的函数头：
const MyEditor: React.FC<{
init: string, // 初始数据
}> = (props) => {
const {init} = props
}
定义useEffect监测init并将其导入编辑器
导入一个类型并定义一个常量
下面的代码写在组件上方，定义在组件外面！
import type { SlateDescendant } from '@wangeditor/editor'
const newNode: { type: string, children: SlateDescendant[] } = { // 生成新节点
type: 'paragraph',
children: []
}
定义useEffect
注意，这个useEffect不能和前面的那个useEffect合并在一起写。之前的useEffect是专门负责在组件卸载时关闭编辑器并释放其内存的。下面这个useEffect是专门负责监测init变动并负责将其注入编辑器！
useEffect(() => {
if (editor) {
editor.select([]) // 全选编辑器中的内容
editor.deleteFragment() // 删除编辑器中被选中内容
SlateTransforms.setNodes(editor, newNode, { mode: "highest" }) // 配置编辑器使用新节点，节点模式设为最高级
editor.dangerouslyInsertHtml(init) // 插入html内容
}
}, [init])
在这个地方趟了不少雷，具体废话不多说了。尤其是官方手册里没有的那句代码SlateTransforms.setNodes，不加会遇到问题！另外注意里面的editor是之前useState生成的编辑器存储器，newNode是在myEditor组件外部上面定义的常量，{mode:“heighest”}参数也必不可少。
工具栏配置
工具栏配置相关内容官方手册写了getConfig、toolbarKeys、insertKeys、excludeKeys一大堆，感觉都是隔靴抓痒的玩意。干货看下面：
import type { IToolbarConfig } from '@wangeditor/editor' // 在组件外面最上方要引入的类型
const toolbarConfig: Partial<IToolbarConfig> = { // 在组件外面上方定义的常量
toolbarKeys: [
'undo', // 取消
'redo', // 重做
'headerSelect', // 标题类型
'fontFamily', // 字体类型
'fontSize', // 字体大小
'lineHeight', // 行高
'|', // 分割线
'bold', // 字体加粗
'italic', // 字体倾斜
'underline', // 下划线
'through', // 删除线
// 'sub', // 上标
// 'sup', // 下标
// "clearStyle", // 清除样式
'color', // 文字颜色
'bgColor', // 背景色
'|', // 分割线
// 'indent', // 增加缩进
// 'delIndent', // 减少缩进
'bulletedList', // 无序列表
'numberedList', // 有序列表
'justifyLeft', // 左对齐
'justifyRight', // 右对齐
'justifyCenter', // 居中
'justifyJustify', // 两端对齐
'|', // 分割线
'divider', // 插入分割线
// 'todo', // 待办
'insertTable', // 插入表格
// "deleteTable", // 删除表格
// "insertTableRow", // 插入表格行
// "deleteTableRow", // 删除表格行
// "insertTableCol", // 插入表格列
// "deleteTableCol", // 删除表格列
// "emotion", // 插入表情符号
'blockquote', // 引用
// 'codeBlock', // 代码块
'uploadImage', // 上传图片
// "uploadVideo", // 上传视频
// "insertImage", // 插入网络图片
// "deleteImage", // 删除图片
// "editImage", // 编辑图片
// "viewImageLink", // 查看图片链接
// "imageWidth30", // 图片宽度设置为30%
// "imageWidth50", // 图片宽度设置为50%
// "imageWidth100", // 图片宽度设置为100%
"insertLink", // 插入链接
// "editLink", // 修改链接
// "unLink", // 删除链接
// "viewLink", // 查看链接
'fullScreen', // 全屏
],
}
最常用的配置都在上面了，还有一些基本上用不到的配置项没列出来，具体可以取官方手册查。使用我的模板会很方便，要用哪个就保留哪个，要禁哪个就注释哪个，按钮的顺序是按照定义的顺序(可以按自己需要调整)，"|"按键之间分割线也可按需要设置。
编辑器配置
我这写一下我用到的字体配置和图片上传配置，我喜欢用简单粗暴json方式配置，不喜欢官方手册里的那种变量属性赋值(有点弯弯绕绕)的写法，请看代码：
import type { IEditorConfig } from '@wangeditor/editor' // 在组件外面最上方要引入的类型
// 在组件内部的代码
const [editor, setEditor] = useState<IDomEditor | null>(null) // 存储 editor 实例
const editorConfig: Partial<IEditorConfig> = {
placeholder: '内容不能为空',
onCreated(editorCase: IDomEditor) {
setEditor(editorCase)
}, // 记录下 editor 实例，重要！
MENU_CONF: {
fontFamily: { // 配置可选字体
fontFamilyList: [
'黑体',
'仿宋',
'楷体',
'宋体',
'微软雅黑',
'Arial',
'Tahoma',
'Courier New',
]
},
uploadImage: { // 配置图片上传服务器
server: '/api/upload',
uploadImage: [], // 不限制上传文件类型
maxNumberOfFiles: 1, // 单次最多上传一个文件
// 单个文件上传成功之后
onSuccess(file: File) {
message.success(`${file.name} 上传成功`) // antd的message组件
},
// 单个文件上传失败
onFailed(file: File) {
message.error(`${file.name} 上传失败`) // antd的message组件
},
// 上传错误，或者触发 timeout 超时
onError(file: File, err: any) {
message.error(`${file.name} 上传出错`+String(err)) // antd的message组件
},
}
}
}
总结
基本上react使用WangEditor按上面的写法基本不会再遇到雷了。另外我写的是typescript，引入很多类型来完善类型提示，ide不会有任何飘红。还有我喜欢在组件外面上方定义很多常量，能在组件外面定义的都放组件外面了。
最后，在antd的表单中中使用wangEditor还有些注意事项，我把我的MyEditor的完整代码贴在下面，有需要的可以看看代码和注释，基本上就没啥问题了。
import React, { useEffect, useImperativeHandle, useRef, useState } from 'react'
import type { ProFormInstance } from '@ant-design/pro-form'
import { ProForm, ProFormSelect, ProFormText } from '@ant-design/pro-form'
import { setNotice } from '@/services/notice'
import { message } from "antd";
import { Editor, Toolbar } from '@wangeditor/editor-for-react'
import type { IDomEditor, IEditorConfig, IToolbarConfig, SlateDescendant } from '@wangeditor/editor';
import { SlateTransforms } from '@wangeditor/editor';
import '@wangeditor/editor/dist/css/style.css'
import '@/components/ul.less'
const sectionList: ApiRes.SelectOption[] = [
{
label: "本部门",
value: 0
},
{
label: "所有部门",
value: 9
},
]
const releaseList: ApiRes.SelectOption[] = [
{
label: "未发布",
value: 0
},
{
label: "已发布",
value: 1
},
]
const newNode: { type: string, children: SlateDescendant[] } = { // 生成新节点
type: 'paragraph',
children: []
}
const toolbarConfig: Partial<IToolbarConfig> = {
toolbarKeys: [
'undo', // 取消
'redo', // 重做
'headerSelect', // 标题类型
'fontFamily', // 字体类型
'fontSize', // 字体大小
'lineHeight', // 行高
'|', // 分割线
'bold', // 字体加粗
'italic', // 字体倾斜
'underline', // 下划线
'through', // 删除线
// 'sub', // 上标
// 'sup', // 下标
// "clearStyle", // 清除样式
'color', // 文字颜色
'bgColor', // 背景色
'|', // 分割线
// 'indent', // 增加缩进
// 'delIndent', // 减少缩进
'bulletedList', // 无序列表
'numberedList', // 有序列表
'justifyLeft', // 左对齐
'justifyRight', // 右对齐
'justifyCenter', // 居中
'justifyJustify', // 两端对齐
'|', // 分割线
'divider', // 插入分割线
// 'todo', // 待办
'insertTable', // 插入表格
// "deleteTable", // 删除表格
// "insertTableRow", // 插入表格行
// "deleteTableRow", // 删除表格行
// "insertTableCol", // 插入表格列
// "deleteTableCol", // 删除表格列
// "emotion", // 插入表情符号
'blockquote', // 引用
// 'codeBlock', // 代码块
'uploadImage', // 上传图片
// "uploadVideo", // 上传视频
// "insertImage", // 插入网络图片
// "deleteImage", // 删除图片
// "editImage", // 编辑图片
// "viewImageLink", // 查看图片链接
// "imageWidth30", // 图片宽度设置为30%
// "imageWidth50", // 图片宽度设置为50%
// "imageWidth100", // 图片宽度设置为100%
"insertLink", // 插入链接
// "editLink", // 修改链接
// "unLink", // 删除链接
// "viewLink", // 查看链接
'fullScreen', // 全屏
],
}
const MyEditor: React.FC<{
init: Props.FormEditor, // 表单初始数据，自定义的namespace Props中的FormEditor类型
onRef: React.RefObject<any>, // 父组件ref，为了在父组件中回调子组件的表单控件
dispatch: (param: { type: string, payload: any }) => void,
}> = (props) => {
const { init, onRef, dispatch } = props
const formRef = useRef<ProFormInstance<Props.FormEditor>>() // 绑定form控件，用来设置表单默认值
useImperativeHandle(onRef, () => ({ formRef })) // 将表单控件暴露给父组件
const [editor, setEditor] = useState<IDomEditor | null>(null) // 存储 editor 实例
const editorConfig: Partial<IEditorConfig> = {
placeholder: '内容不能为空',
onCreated(editorCase: IDomEditor) {
setEditor(editorCase)
}, // 记录下 editor 实例，重要！
MENU_CONF: {
fontFamily: { // 配置可选字体
fontFamilyList: [
'黑体',
'仿宋',
'楷体',
'宋体',
'微软雅黑',
'Arial',
'Tahoma',
'Courier New',
]
},
uploadImage: { // 配置图片上传服务器
server: '/api/upload',
uploadImage: [],
maxNumberOfFiles: 1, // 单次最多上传一个文件
// 单个文件上传成功之后
onSuccess(file: File) {
message.success(`${file.name} 上传成功`)
},
// 单个文件上传失败
onFailed(file: File) {
message.error(`${file.name} 上传失败`)
},
// 上传错误，或者触发 timeout 超时
onError(file: File, err: any) {
message.error(`${file.name} 上传出错` + String(err))
},
}
}
}
useEffect(() => {
formRef.current?.setFieldsValue(init) // 初始化表单默认值
if (editor) {
editor.select([]) // 全选编辑器中的内容
editor.deleteFragment() // 删除编辑器中被选中内容
SlateTransforms.setNodes(editor, newNode, { mode: "highest" }) // 配置编辑器使用新节点，节点模式设为最高级
editor.dangerouslyInsertHtml(init.desc) // 插入html内容
}
}, [init])
useEffect(() => { // 及时销毁editor，防止内存泄露！
return () => {
if (editor == null) return
editor.destroy()
setEditor(null)
}
}, [editor])
return (
<ProForm
formRef={formRef}
submitter={{ render: () => <></> }}
style={{ margin: 0, padding: 0 }}
onFinish={async (values: any) => {
const result = { ...values, desc: editor!.getHtml(), noticeId: init.noticeId }
const msg = await setNotice(result) // 提交数据到服务器
if (msg.state) {
message.success(msg.message)
// 刷新通知数据及当前通知状态
dispatch({ type: "notice/refreshNotice", payload: { param: "edit", id: msg.data } })
} else {
message.error(msg.message)
}
}}
>
<ProForm.Group>
<ProFormText
width={700}
name="title"
label="通知标题"
placeholder="请输入通知标题"
validateTrigger="onBlur"
rules={[
{
required: true,
message: '请输入通知标题！',
},
{
min: 2,
message: '标题最少2个字！'
},
{
max: 50,
message: '标题最多50个字！'
}
]}
/>
<ProFormSelect
width={160}
name="sectionId"
label="通知机构"
fieldProps={{
defaultValue: 0,
}}
placeholder="请选择通知范围"
options={sectionList}
rules={[
{
required: true,
message: '请选择通知范围！',
},
]}
/>
<ProFormSelect
width={160}
name="releaseStatus"
label="发布状态"
fieldProps={{
defaultValue: 0,
}}
placeholder="请选择发布状态"
options={releaseList}
rules={[
{
required: true,
message: '请选择发布状态！',
},
]}
/>
<ProForm.Item
label="通知内容"
name="desc"
rules={[
{
required: true,
validator: () => {
if (editor === null) {
return Promise.reject('内容不能为空')
} else if (editor.getText().length < 3) {
return Promise.reject('内容不能少于3个字符')
} else {
return Promise.resolve()
}
},
},
]}
>
<div style={{ border: '1px solid #ccc', zIndex: 100, width: 1188 }}>
<Toolbar
editor={editor}
defaultConfig={toolbarConfig}
mode="simple"
style={{ borderBottom: '1px solid #ccc' }}
/>
<Editor
defaultConfig={editorConfig}
defaultHtml={init.desc}
mode="simple"
style={{
height: '420px',
margin: 0,
padding: 0,
marginBottom: 65,
overflowY: 'hidden'
}}
/>
</div>
</ProForm.Item>
</ProForm.Group>
</ProForm>
)
}
export default MyEditor