md-editor-v3 图片上传:prop 绑定与两种上传模式
md-editor-v3 上传图片后只插入一个空链接,通常是监听写成了 @on-upload-img。这个组件把 onUploadImg 声明为 prop,同时用同名事件抛出;只有 :onUploadImg="handler" 这种 prop 绑定能命中,事件写法会被 Vue 编译成另一个名字。
监听为什么落空
常见的错误写法是把它当成普通事件:
<MdEditor v-model="content" @on-upload-img="onUploadImg" />
Vue 编译器会把 @on-upload-img 转成 onOnUploadImg。用 @vue/compiler-dom 3.5.34 对两种写法做编译,输出很直接:
# 模板:<MdEditor @on-upload-img="handler" />
return (_openBlock(), _createBlock(_component_MdEditor, {
onOnUploadImg: _ctx.handler
}, null, 8 /* PROPS */, ["onOnUploadImg"]))
# 模板:<MdEditor :onUploadImg="handler" />
return (_openBlock(), _createBlock(_component_MdEditor, {
onUploadImg: _ctx.handler
}, null, 8 /* PROPS */, ["onUploadImg"]))
md-editor-v3 7.1.0 的类型声明里,onUploadImg 是一个 prop,事件列表里也有同名项。组件内部读取的是 props.onUploadImg,所以 onOnUploadImg 不会触发上传逻辑。编辑器没有拿到 URL,就按默认行为插入一个没有地址的图片占位,看起来像“上传成功但图片是空的”。
正确的写法是:
<MdEditor
v-model="content"
language="zh-CN"
:footers="[]"
placeholder="Markdown 正文,可直接粘贴截图上传图片"
:onUploadImg="onUploadImg"
/>
同一类问题也会出现在其他“prop 与 emit 同名”的组件上。判断方法不是看文档标题,而是看组件声明:如果它是 prop,就用 :;如果只有 emit,才用 @。
最小复现
建一个只打印日志的最小页面,就能确认监听到底有没有进来:
<script setup lang="ts">
const text = ref('')
const calls: string[] = []
const onUploadImg = (files: File[], callback: (urls: string[]) => void) => {
calls.push('hit')
console.log('upload invoked:', files.length)
callback([])
}
</script>
<template>
<MdEditor v-model="text" @on-upload-img="onUploadImg" />
</template>
在编辑器里粘贴一张截图,会出现三个结果:
- 控制台没有
upload invoked,calls.length仍为 0。 - 正文里出现一个没有地址的图片语法。
- Vue 开发者工具里,该组件的 attrs 上是
onOnUploadImg,而组件实际读的是onUploadImg。
把模板改成 :onUploadImg="onUploadImg" 再试,日志立刻打印,callback 收到的数组决定插入几张图。这个对照实验不需要对象存储,也不需要后端接口,是最快的定位方式。
组件类型声明里也能直接看出来(示意):
interface MdEditorProps {
onUploadImg?: (files: File[], callback: (urls: string[]) => void) => void | Promise<void>
}
一个 prop 和一个 emit 同名在 Vue 里并不冲突:prop 走 props.onUploadImg,emit 走 onOnUploadImg。组件作者保留两者,是为了同时支持受控调用和事件监听;但对使用者来说,只有 prop 那条路会真正执行上传逻辑,所以模板里必须用 :。
上传处理函数
处理函数接收文件数组和一个回调。逐个上传,收集 URL,最后一次性回调:
const { upload } = useUploader('content')
const onUploadImg = async (files: File[], callback: (urls: string[]) => void) => {
const urls: string[] = []
let failed = 0
for (const file of files) {
try {
const url = await upload(file)
if (url) {
urls.push(url)
} else {
failed++
}
} catch {
failed++
}
}
if (urls.length) {
callback(urls)
}
if (failed) {
message.error(`${failed} 张图片上传失败`)
}
}
三个细节值得注意:
callback只调一次,传完整数组。逐文件回调会让编辑器插入顺序错乱。- 失败时不回调,只提示。回调空数组会让编辑器插入空链接,反而掩盖错误。
- 上传函数要返回最终 URL。无论是预签名还是后端中转,编辑器只认这个字符串。
如果上传封装复用了 Element Plus 的 UploadRequestOptions 类型,调用时需要补齐 action、method、headers、data、withCredentials、onError、onProgress 等字段。只关心文件和进度时,其余字段用默认值占位即可;更好的做法是在封装层收敛成自定义参数类型,避免调用方到处写类型断言。
两种上传模式
图片上传通常有两条路径,选择取决于对象存储和后端能力:
| 模式 | 请求路径 | 适用存储 | 注意点 |
|---|---|---|---|
| 预签名直传 | 先取预签名 URL,再 PUT 到对象存储 | S3/Minio 等支持预签名的服务 | 不能用 FormData;Content-Type 要和签名时一致 |
| 后端中转 | 文件先传到 /api/upload | 后端统一转发 | 大文件会占用后端带宽和内存 |
预签名模式的核心代码如下:
const isDirectUpload = UPLOAD_MODE === 'client'
const upload = async (file: File): Promise<string> => {
if (!isDirectUpload) {
const res = await api.upload(file, { directory: 'content' })
return res.data
}
const presigned = await api.getPresignedUrl(file.name, 'content')
await fetch(presigned.uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': file.type || 'application/octet-stream' },
body: file
})
await api.createFileRecord({ ...presigned, name: file.name, size: file.size })
return presigned.url
}
两个容易忽略的点:
- 预签名上传不能用
FormData。对象存储的预签名 URL 只接受原始文件体,Content-Type必须和签名时使用的一致。 - 文件记录通常是异步写入。上传成功但列表里暂时看不到文件,刷新后出现,属于最终一致性,不是上传失败。
上传目录不要直接拼接用户输入。传 content 这类固定值,日期和文件名由后端或上传封装生成,避免路径穿越或覆盖同名文件。示例里的目录结构可以理解为 content/<日期>/<文件名>。
失败排查
上传链路涉及编辑器、上传封装、对象存储和后端记录,按层排查最快:
| 现象 | 可能原因 | 检查点 |
|---|---|---|
| 正文只出现空的图片语法 | 监听写法错误或 callback 未调用 | 确认 :onUploadImg,确认 urls.length > 0 |
| 提示上传失败 | 预签名请求 403、CORS、Content-Type 不匹配 | Network 面板看 PUT 响应与请求头 |
| 上传成功但文件列表没有记录 | 文件记录异步未完成 | 刷新后是否出现 |
| 图片 404 | 返回的 URL 不是公开地址 | 检查对象存储域名与路径 |
| 多图顺序错乱 | 每个文件都调用了 callback | 改为收集后一次回调 |
预签名上传的 403 通常不是密钥错误,而是浏览器在 PUT 时带了和签名不一致的 Content-Type,或者对象存储的 CORS 没允许当前域名。先看请求头,再看桶策略。
FAQ
上传成功但正文插入空图片是为什么?
编辑器没有收到上传回调。最常见是 @on-upload-img 被编译成 onOnUploadImg,组件读不到;其次是处理函数没有调用 callback,或者传入的是空数组。
预签名上传返回 403 怎么查?
先看 PUT 请求的 Content-Type 是否和签名时一致,再看对象存储的 CORS 是否允许当前域名,最后确认预签名 URL 是否过期。密钥错误通常会直接体现在签名接口,而不是 PUT 阶段。
为什么上传封装要补齐 Element Plus 的字段?
复用了 UploadRequestOptions 类型时,它要求 action、method、headers 等字段。这里只传文件和回调,其他字段用默认值补齐,类型上需要断言。封装层收敛成自定义参数类型后就可以去掉。
多图上传回调应该调几次?
一次,传完整 URL 数组。逐文件回调会让编辑器按回调顺序插入,异步完成顺序不一致时图片顺序就会乱。
上传目录应该怎么定?
用固定前缀(如 content)+ 服务端生成的日期和文件名。不要把用户输入直接拼进目录,也不要让同名文件互相覆盖。
小结
md-editor-v3 图片上传的关键只有两点:用 prop 绑定 onUploadImg,处理函数收集完 URL 后一次回调。剩下的复杂度在上传模式:预签名直传要处理 Content-Type 和 CORS,后端中转要注意带宽。把编辑器、上传封装和对象存储的分层理清,排查时就不会在 Vue 事件名和存储策略之间来回猜。写完 Markdown 可以用 Markdown 编辑器 预览格式,从旧内容迁移时用 HTML 转 Markdown 先转再校对。更多前端实践见 前端开发。
评论
还没有评论,来说两句吧