md-editor-v3 图片上传:prop 绑定与两种上传模式

2026-11-19 前端开发 有希 38 次浏览

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>

在编辑器里粘贴一张截图,会出现三个结果:

  1. 控制台没有 upload invoked,calls.length 仍为 0。
  2. 正文里出现一个没有地址的图片语法。
  3. 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} 张图片上传失败`)
  }
}

三个细节值得注意:

  1. callback 只调一次,传完整数组。逐文件回调会让编辑器插入顺序错乱。
  2. 失败时不回调,只提示。回调空数组会让编辑器插入空链接,反而掩盖错误。
  3. 上传函数要返回最终 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 先转再校对。更多前端实践见 前端开发。

评论

登录后即可参与评论

还没有评论,来说两句吧

相关文章