图片上传

图片能力由两部分组成:

能力	入口
上传文件、粘贴图片、拖拽图片	`uploadImage`
限制可选文件类型	`editorBehaviorOptions.image.accept`
工具栏图片上传是否允许多选	`editorBehaviorOptions.image.multiple`
是否显示网络图片入口	`editorBehaviorOptions.image.allowUrl`
上传前裁剪	`editorBehaviorOptions.image.crop`

vue

<script setup lang="ts">
import type { EditorBehaviorOptions, UploadImage } from 'tiptap-vue-pro-element-plus'

const uploadImage: UploadImage = async (file) => {
  const formData = new FormData()
  formData.append('file', file)
  const res = await fetch('/api/upload', { method: 'POST', body: formData })
  const { url } = await res.json()
  return url
}

const editorBehaviorOptions: EditorBehaviorOptions = {
  image: {
    accept: 'image/png,image/jpeg,image/webp',
    multiple: true,
    allowUrl: true,
    crop: {
      enabled: true,
      aspectRatio: 16 / 9,
      quality: 0.9,
    },
  },
}
</script>

<template>
  <ProEditorElementPlus
    v-model="content"
    :upload-image="uploadImage"
    :editor-behavior-options="editorBehaviorOptions"
  />
</template>

image.multiple 默认 false,保持一次只选择一个文件。设置为 true 后,工具栏图片上传会按选择顺序逐个调用 uploadImage 并插入。粘贴和拖拽仍沿用已有批量图片处理能力。

image.allowUrl 默认 true,用于显示「网络图片」入口。设置为 false 后,如果只配置了 uploadImage,工具栏会直接显示「上传图片」按钮,不会再出现图片下拉菜单。

image.crop 默认关闭。设置为 true 时会在工具栏选图后打开裁剪弹窗,默认按 1:1 居中裁剪;也可以传 { enabled: true, aspectRatio: 16 / 9 } 这类配置用于封面图。裁剪只作用于工具栏按钮选图,粘贴和拖拽图片仍直接上传原图,避免打断截图粘贴流程。

uploadImage 返回 null 时会跳过插入;抛错时会触发 Adapter 注入的消息提示。Core 不关心文件上传到 OSS、COS、S3 还是业务后端,只关心最后拿到可访问的 URL。

本地 Mock 上传

还没有后端接口时,可以用 URL.createObjectURL(file) 先验证工具栏上传、粘贴和拖拽流程:

const uploadImage: UploadImage = async (file) => {
  await new Promise((resolve) => window.setTimeout(resolve, 300))
  return URL.createObjectURL(file)
}

blob: URL 只在当前浏览器会话内有效,刷新后可能失效。生产环境必须返回持久化 URL。

常见排查

没有上传入口:确认传入了 uploadImage,并且自定义 toolbar 没有移除 image 按钮。
选择文件后没插入:确认 uploadImage 返回的是可访问 URL,不是 undefined。
文件选不了:检查 editorBehaviorOptions.image.accept 是否包含当前 MIME 类型。
大图被跳过:检查 editorBehaviorOptions.image.maxSize。
只想上传不想输入 URL:设置 editorBehaviorOptions.image.allowUrl=false。

视频、音频和通用文件上传见视频、音频和文件上传。

图片上传 ​

本地 Mock 上传 ​

常见排查 ​

图片上传

本地 Mock 上传

常见排查