mavonEditor 图片上传接入指南:文件服务器与 base64 两种方案及图片方法 API 全解析

原创2026-10-14 21:33:091,368 阅读
文章标签:前端UI组件富文本

mavonEditor 图片上传接入指南:文件服务器与 base64 两种方案及图片方法 API 全解析

mavonEditor 是基于 Vue 的 Markdown 编辑器组件,其图片上传不内置任何特定后端,而是通过 imgAdd / imgDel 事件把「选中图片 → 本地占位 → 上传服务器 → 替换占位符」整条链路交给业务方自行实现。本文将围绕仓库文档 doc/en/upload-images.md(及对应的 doc/cn/upload-images.md)展开,完整讲解两种图片上传方案(上传至文件服务器、直接转为 base64)、七种图片相关方法的参数与行为,并结合 src/mavon-editor.vue 与 src/components/md-toolbar-left.vue 的源码,讲清事件触发时序与占位符替换的底层原理。读完本文,你可以直接在自己的 Vue 项目中接入任意后端接口完成图片上传,并掌握按文件名管理、批量替换 URL 等进阶用法。

mavonEditor 插入图片的操作演示

一、图片上传的总体机制:占位符 + 事件回调

mavonEditor 的图片上传遵循一条固定的数据流:

  1. 用户点击工具栏图片按钮或拖拽/粘贴图片,左侧工具栏组件 src/components/md-toolbar-left.vue 读取文件;
  2. 编辑器在 Markdown 源码中插入一个本地占位符,形如 文件名(0 是内部图片编号,编号从 1 递增,pos 即该编号);
  3. 同时向外部发射 imgAdd(pos, $file) 事件,把编号与 File 对象交给业务方;
  4. 业务方用 axios 等工具将文件上传到自己的服务器,拿到真实 URL;
  5. 调用 $vm.$img2Url(pos, url) 等方法,把占位符替换为真实地址,完成闭环。

删除图片时,编辑器发射 imgDel 事件,业务方在此清理缓存或调用后端删除接口;组件内部则会用正则将 name 从 d_value 中移除(见 src/mavon-editor.vue)。

组件内外部事件的中转逻辑位于 src/mavon-editor.vue:内部 $imgAdd(pos, $file, isinsert) 先通过 FileReader.readAsDataURL 读取文件(默认仅接受 image/* 类型的文件,__rFilter = /^image\//i),生成预览用 miniurl,并把文件名中 [ ] ( ) + { } & | \ * ^ % $ # @ - 等特殊字符去除后作为 _name,随后以 _name 形式插入光标位置,最后 $emit('imgAdd', pos, $file) 通知外部。也就是说,你收到的 $file 上会附带 miniurl(DataURL 预览)与 _name(净化后的文件名)两个额外字段。

二、方式一:图片上传至文件服务器

这是最常规的生产方案:图片先传给自己的后端(对象存储、图床、CDN 均可),再把返回的 URL 写回 Markdown。

2.1 每次添加图片即触发上传

在模板中绑定 @imgAdd 与 @imgDel 两个事件,$imgAdd(pos, $file) 中完成「组装 FormData → 上传 → 用 URL 替换占位符」三步:

<template>
    <mavon-editor ref=md @imgAdd="$imgAdd" @imgDel="$imgDel"></mavon-editor>
</template>
exports default {
    methods: {
        // bind @imgAdd event
        $imgAdd(pos, $file){
           // step 1. upload image to server.
           var formdata = new FormData();
           formdata.append('image', $file);
           axios({
               url: 'server url',
               method: 'post',
               data: formdata,
               headers: { 'Content-Type': 'multipart/form-data' },
           }).then((url) => {
               // step 2. replace url ... -> ...
               // $vm.$img2Url. The details at the end of this page
               $vm.$img2Url(pos, url);
           })
        }
    }
}

要点说明:

  • pos 是编辑器分配的图片编号(如 0),$file 是 File 对象;
  • 上传接口返回的 url 可以是任意可访问的图片地址;
  • $img2Url(pos, url) 负责把 Markdown 源码里的 ... 正则替换为 ...(实现见 src/mavon-editor.vue),并同步更新工具栏的图片缓存,随后重新渲染预览。

2.2 统一上传多张图片(攒批模式)

如果不想每选一张图就发一次请求,可以先在 $imgAdd 中把文件缓存到本地对象 img_file,在 $imgDel 中移除缓存,再由业务按钮(如「上传」)统一提交:

<template>
    <button @click="uploadimg">upload</button>
    <mavon-editor ref=md @imgAdd="$imgAdd" @imgDel="$imgDel"></mavon-editor>
</template>
exports default {
    data(){
        return {
            img_file: {}
        }
    },
    methods: {
        // bind @imgAdd event
        $imgAdd(pos, $file){
            // cache images info
            this.img_file[pos] = $file;
        },
        $imgDel(pos){
            delete this.img_file[pos];
        },
        uploadimg($e){
           // step 1. upload images to server.
            var formdata = new FormData();
            for(var _img in this.img_file){
                formdata.append(_img, this.img_file[_img]);
            }
            axios({
                url: 'server url',
                method: 'post',
                data: formdata,
                headers: { 'Content-Type': 'multipart/form-data' },
            }).then((res) => {
                /**
                 * eg:res = [[pos, url], [pos, url]...]
                 */
                // step 2. replace url ... -> ...
                for (var img of res) {
                    // $vm.$img2Url. The details at the end of this page
                    $vm.$img2Url(img[0], img[1]);
                }
            })
        },
    }
}

这里要求后端接口返回一个二维数组 [[pos, url], [pos, url], ...]:每一项的 pos 必须与前端缓存的图片编号一一对应,url 是对应图片的最终地址。随后循环调用 $vm.$img2Url(img[0], img[1]) 逐个替换。若后端返回结构与上述约定不同,也可在 .then 中自行做数据映射后再调用。

仓库自带的演示页面 src/dev/app.vue 就是这一模式的完整示例:$imgAdd 中执行 this.img_file[pos] = $file 缓存文件,$imgDel 中执行 delete this.img_file[pos],uploadimg 中则通过 this.$refs.md.$img2Url(_img, url) 完成替换,可直接对照阅读。

三、方式二:直接将图片保存为 base64 编码

若图片体积小、无需后端参与,可以把图片以 DataURL(base64)形式直接写入 Markdown 源码,前端即可独立完成:

<template>
    <mavon-editor ref=md @imgAdd="$imgAdd" v-model="mdStr" @imgDel="$imgDel"></mavon-editor>
</template>
exports default {
    data() {
        return {
            mdStr: '### demo \n image'
        };
    },
    mounted() {
        // init: replace <img src="base64">
        this.$nextTick(() => {
            // $vm.$imgUpdateByUrl. The details at the end of this page
            $vm.$imgUpdateByUrl('./0', base64);
        }
    },
    methods: {
        $imgAdd(pos, $file){
            // upload image(base64)
           var formdata = new FormData();
           formdata.append('image', $file);
           axios({
               url: 'server url',
               method: 'post',
               data: formdata,
               headers: { 'Content-Type': 'multipart/form-data' },
           }).then((flag) => {
           })
        }
    }
}

这种方式的要点是:

  • 初始 mdStr 里可以用 image 这类占位写法预留图片位置;
  • 在 mounted 的 $nextTick 中调用 $vm.$imgUpdateByUrl('./0', base64),把占位路径 ./0 与 base64 字符串建立映射;
  • $imgUpdateByUrl(pos, url) 内部执行 this.markdownIt.image_add(pos, url) 并触发重渲染(见 src/mavon-editor.vue),渲染层即可正确显示该图片。image_add / image_del 方法来自 markdown-it-images-preview 插件(在 src/lib/mixins/markdown.js 引入,initMarkdown 中通过 .use(miip) 注册,见该文件第 95 行)。

需要说明的是,base64 方案虽然免去了服务器,但会显著增大 Markdown 文本体积,通常只适合小图标或压缩后的预览图;大图仍建议走方式一。

四、图片方法 API 全表

官方文档(doc/en/upload-images.md)给出了七个可直接调用的图片方法,下表完整罗列其名称、参数与行为:

方法名 参数 描述
$vm.$refs.toolbar_left.$imgDelByFilename(≥2.1.6) String: filename 按文件名删除对应图片文件,成功返回 true,失败返回 false(≥2.4.16 起同时会将该图片从 md 源码中移除)
$vm.$refs.toolbar_left.$imgAddByFilename(≥2.1.6) String: filename, File: file 按文件名添加图片文件(文件别名须为 ./filename 样式),成功返回 true,失败返回 false
$vm.$refs.toolbar_left.$imgUpdateByFilename(≥2.1.6) String: filename, File: file 按文件名更新对应图片文件(别名须为 ./filename 样式),成功返回 true,失败返回 false
$vm.$imgUpdateByUrl(≥2.1.6,中文文档标注 ≥2.1.5) String: filename, String: url 将 <img> 标签 src 的相对路径值替换为 url(如 ./0 → http://path/to/png/some.png)
$vm.$imgAddByUrl(≥2.1.11) String: filename, String: url 同上(如 ./0 → http://path/to/png/some.png)
$vm.$img2Url(≥2.1.11) String: filename, String: url 将 md 源码中的图片文件名替换为 url(如 h → ![h](http://path/to/png/some.png))
$vm.$imglst2Url(≥2.1.11) Array: filenameLst 同上,批量处理(filenameLst 为 [[filename, url], ...] 数组)

表格中的版本号是文档标注的引入版本要求,具体可用版本请以当前安装的 mavonEditor 版本为准。

前三个方法定义在左侧工具栏组件 src/components/md-toolbar-left.vue(分别见第 235、246、264 行),后四个方法定义在组件根 src/mavon-editor.vue(见第 482–510 行)。其中 $img2Url 的实现会动态构造正则 /(!\[[^\[\]]*?\]\(?\=\()\(\s*(fileIndex)\s*\)/g,把源码中对应的占位符整体替换为 URL,并调用 toolbar_left.$changeUrl(fileIndex, url) 同步图片缓存,最后 iRender() 重渲染(src/mavon-editor.vue)。$imglst2Url 则遍历数组逐项调用 $img2Url(src/mavon-editor.vue)。

五、获取 $vm 实例的两种方式

文档中所有方法都以 $vm 为调用主体,$vm 即 mavonEditor 组件实例,可通过两种方式取得:

  1. 通过引入对象获取:使用 import {mavonEditor} from ... 等方式引入后,$vm 即为 mavonEditor;
  2. 通过 $refs 获取:在模板中声明 ref,如 <mavon-editor ref=md></mavon-editor>,此时 $vm 为 this.$refs.md。

方式 2 在父子组件场景中更常用,仓库演示页 src/dev/app.vue 即以 this.$refs.md.$imglst2Url(...)、this.$refs.md.$img2Url(...) 形式调用。

六、进阶:文件管理、过滤与预览的源码级补充

6.1 图片缓存的数据结构

左侧工具栏内部用 img_file 数组维护图片列表,每一项形如 <a href="https://link.gitcode.com/i/487476b1525d626f2a73f3da12072da5" target="_blank">编号, File对象](见 [src/components/md-toolbar-left.vue 的 $imgFileAdd)。$imgDelByFilename 会遍历该数组,通过 isEqualName 对比原文件名或净化后的 _name 找到对应项后调用 $imgDel 删除(第 235–245 行)。因此按文件名管理图片的前提是:外部传入的 filename 与选择文件时的原始文件名一致,或使用 ./filename 别名样式。

6.2 用 imageFilter 过滤图片类型

组件提供 imageFilter prop(类型为 Function,默认 null,见 src/mavon-editor.vue),可在图片入库前做自定义校验。工具栏的 $imgFilesAdd 会先判断:若 image_filter 是函数则仅当 image_filter($files<a href="https://link.gitcode.com/i/b17f87c4d7add83dcf77e912c67cdd8b" target="_blank">i]) === true 时才加入;否则退化为内置的 $files[i].type.match(/^image\//i) MIME 类型检查([src/components/md-toolbar-left.vue)。可据此限制格式(如仅允许 PNG/JPG)或文件大小。

6.3 渲染层的图片点击预览

渲染层对图片做了点击事件监听:点击预览区中的 <img> 时,若设置了 imageClick 回调则交给回调处理,否则在组件内部打开全屏预览(d_preview_imgsrc),实现位于 src/lib/core/extra-function.js。这意味着无论采用哪种上传方式,最终渲染出的图片都自动具备点击放大能力,无需业务额外实现。

七、实践小结与注意事项

  • 占位符编号是桥梁:pos 在「本地占位 → 上传回调 → 替换 URL」全过程中必须保持一致,批量上传时后端返回的 pos 一定要与前端一致,否则会出现 URL 错位;
  • imgDel 别忘了清缓存:业务侧应在 $imgDel(pos) 中同步删除 img_file 缓存项,避免内存中残留已删除的大文件对象;
  • $file 附带字段:收到的 $file 上附有 miniurl(DataURL 预览)与 _name(去除特殊字符的文件名),按文件名操作图片时应使用这些字段对应的规则;
  • 方案选择:生产环境大图优先走「文件服务器」方案,小图或离线场景可考虑 base64,但要注意文本体积膨胀;
  • 参考实现:完整的端到端示例可对照 src/dev/app.vue 的 $imgAdd / $imgDel / uploadimg / imgreplace 方法阅读,官方文档另见 doc/en/upload-images.md 与 doc/cn/upload-images.md。

掌握上述事件模型与七个方法,即可将 mavonEditor 无缝接入任意自建图床、云存储或既有文件服务,实现完全由业务方掌控的图片上传链路。

登录后查看全文
mavonEditor