电子保函模板编辑器实战一：基于 WangEditor 的富文本编辑器实践定制

作者：袖梨 2026-07-15

我用 WangEditor 做了个模板编辑器，说说踩过的坑

1. 为什么要做这个编辑器

这个项目的背景是这样的：保险保单/保函业务需要适配全国各地的差异化要求，模板数量多、更新频繁。之前一直是业务提需求，开发人员在代码里硬编码维护，一来一回沟通成本很高，理解上还容易有偏差，而且每次改模板都得等发版才能生效，响应速度跟不上业务节奏。

所以这次要做的，是一个让业务人员能自主配置的模板编辑器。核心目标很明确：业务人员自己可视化编辑模板、自己测试、自己管理版本、自己发布，不用再依赖开发人员介入。

这个编辑器的具体目标是让业务人员维护“报文模板”。模板里不只有普通文字，还会有各种变量，比如投保人姓名、保单金额这些。用户编辑完之后，系统得把内容转换成 FreeMarker 模板，也就是 FTL 报文，交给后端去渲染。

所以我要解决的问题其实是这些：

基础排版得有：字体、字号、颜色、加粗、对齐、缩进这些。
变量得能插入，而且看起来不能像一串 {{xxx}}，得像个正常的标签。
变量插入完不是终点，最后生成 FTL 的时候还要能变回去。
模板有附页，得能标记分页位置。
页眉有两张图片，左右各一张，还能单独删掉。
有些内容需要边框，编辑时看着是边框，生成时得转成 FTL 能识别的结构。

这么一看，问题就不是“找个编辑器让用户打字”了，而是要找一个能深度扩展、能控制文档结构、能打通编辑态和生成态的编辑器。

2. 为什么选 WangEditor

选 WangEditor 不是因为它有多完美，而是它刚好满足了几个关键条件：

基础排版功能现成的，不用从零写。
有 Vue 3 组件，接入起来方便。
底层是 Slate.js，文档是节点树结构，不是一团不可控的 HTML。

特别是第三点，Slate 的节点树结构让我能把“变量标签”“附页标记”这些业务概念变成编辑器真正认识的节点。

不过选了 WangEditor 不代表后面就顺利了。真正花时间的地方，都在它的扩展边界上：哪些节点要做成 inline，哪些要做成 void，哪些内容要序列化，哪些只在编辑态展示。

3. 这个编辑器里扩展了哪些业务元素

根据源码里的实现，编辑器主要扩展了 5 类自定义元素：

功能	Slate type	节点特点	作用
变量标签	`variable`	inline void	编辑态展示蓝色标签，生成态转换为变量占位符
附页标记	`followerMarker`	block void	表示附页开始位置，生成时带分页样式
边框容器	`borderBox`	block 容器	插入上下边框或全边框区域
页眉容器	`headerContainer`	block 容器	页眉布局容器
页眉图片容器	`headerImageContainer`	block void	放置左右两张页眉图片，并支持单独删除

这几个节点的性质不一样，所以处理方式也不一样。

比如变量标签要和普通文字排在同一行，所以它是 inline；但它不能让用户把光标放进标签内部编辑，所以它又是 void。附页标记和页眉图片容器是独立块级内容，所以它们不是 inline。页眉图片容器还要避免内部图片被 Slate 当成普通子节点处理，因此也被标记成 void。

在 handleCreated 里，编辑器会重写 editor.isVoid 和 editor.isInline：

 复制代码editor.isVoid = (element) => {
    const type = (element as { type?: string }).type
    if (type === 'variable' || type === 'followerMarker' || type === 'headerImageContainer') return true
    return originalIsVoid(element)
}editor.isInline = (element) => {
    const type = (element as { type?: string }).type
    if (type === 'variable') return true
    if (type === 'followerMarker' || type === 'borderBox' || type === 'headerContainer' || type === 'headerImageContainer') return false
    return originalIsInline(element)
}

这一步很重要，因为它决定了这些业务元素在 Slate 文档树里的行为。

4. 自定义元素要打通三条链路

在 WangEditor 里，一个自定义元素不是只写一个渲染函数就结束了。它至少要打通三条链路：

 复制代码registerRenderElem     编辑态怎么显示
registerParseElemHtml  HTML 怎么还原成 Slate 节点
registerElemToHtml     Slate 节点怎么序列化成 HTML

拿变量标签来说，编辑态要显示成一个不可编辑的蓝色标签；保存 HTML 时要带上 data-variable、data-label 和样式字段；再次加载 HTML 时，又要能根据这些属性还原成 type: 'variable' 的 Slate 节点。

也就是说，这里不是简单地“插入一段 span”。如果只插入普通 HTML，编辑器下一次解析、保存、生成 FTL 的时候都很容易丢信息。变量必须成为编辑器文档树里的正式节点。

5. 变量标签为什么要保存自己的样式

变量是这个编辑器里最麻烦、也最关键的元素。

在编辑器里，变量看起来是一个标签，例如“投保人姓名”。但生成模板时，它要变成类似 {{xxx}} 的占位符。更进一步，如果用户给这个变量设置了字号、颜色、加粗，那么这些样式也要跟着变量一起进入最终 FTL。

源码里的做法是：变量节点自己保存样式字段，例如：

 复制代码{
    type: 'variable',
    label,
    prop,
    fontSize,
    color,
    fontWeight,
    fontFamily,
    fontStyle,
    textDecoration,
    children: [{ text: '' }],
}

序列化成 HTML 时，这些字段会写成 data-font-size、data-color、data-font-weight 等属性；生成报文前，再通过 convertVariablesForGenerate 把它们编码进占位符：

 复制代码{{prop}}
{{prop||font-size:14pt;color:#000;font-weight:bold}}

这么做的原因很实际：变量是 void 节点，Slate 普通的 mark 机制不会自然作用到它内部的空文本节点上。如果只依赖选区上下文，变量一旦复制、移动、保存再回显，样式就容易丢。

所以代码里拦截了 editor.addMark 和 editor.removeMark。当选区覆盖变量节点时，不是只给普通文本加 mark，而是用 Transforms.setNodes 直接更新变量节点本身：

 复制代码editor.addMark = (key: string, value: unknown) => {
    const varPaths = getSelectedVariablePaths()
    if (varPaths.length > 0) {
        varPaths.forEach((varPath) => {
            if (key === 'bold') {
                Transforms.setNodes(editor, { fontWeight: value ? 'bold' : '' }, { at: varPath })
            } else if (key === 'color' || key === 'fontSize' || key === 'fontFamily') {
                Transforms.setNodes(editor, { [key]: value }, { at: varPath })
            }
        })
    }
    originalAddMark.call(editor, key, value)
}

这部分逻辑看起来有点绕，但解决的是一个很具体的问题：变量不是普通文字，但用户对它的操作又应该像普通文字一样自然。

6. 编辑态和生成态之间怎么转换

这个系统有两个状态：

编辑态：变量是可视化标签，附页是可见标记，页眉图片可以删除。
生成态：变量要变成占位符，附页要变成分页结构，边框和页眉要变成适合 FTL 输出的 HTML。

变量的转换分两步。

编辑态生成报文时，getGenerateContent 会先拿到编辑器 HTML，然后调用 convertVariablesForGenerate，把带 data-variable 的元素替换成 {{prop}} 或 {{prop||style}}。

从生成内容回显到编辑器时，setGenerateContent 会调用 restoreVariablesFromGenerate。它先用 setHtml 加载内容，再在 Slate 文档树中查找 {{prop}} 占位符，找到一个就删除文本，再插入一个真正的 variable 节点。

这里没有直接拼一段 HTML 再塞回编辑器，而是通过 Slate API 插入节点。这样做更稳，因为后续选中、高亮、工具栏格式联动都依赖这个节点类型。