mavonEditor 图片上传接入指南:文件服务器与 base64 两种方案及图片方法 API 全解析
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 的图片上传遵循一条固定的数据流:
- 用户点击工具栏图片按钮或拖拽/粘贴图片,左侧工具栏组件 src/components/md-toolbar-left.vue 读取文件;
- 编辑器在 Markdown 源码中插入一个本地占位符,形如
文件名(0是内部图片编号,编号从 1 递增,pos即该编号); - 同时向外部发射
imgAdd(pos, $file)事件,把编号与File对象交给业务方; - 业务方用
axios等工具将文件上传到自己的服务器,拿到真实 URL; - 调用
$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 → ) |
$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 组件实例,可通过两种方式取得:
- 通过引入对象获取:使用
import {mavonEditor} from ...等方式引入后,$vm即为mavonEditor; - 通过
$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 无缝接入任意自建图床、云存储或既有文件服务,实现完全由业务方掌控的图片上传链路。
