EveryWhereUpload

@mbjia/components

EveryWhereUpload

全局素材上传控制器，处理文件上传、文件夹上传、上传恢复、进度、失败重试和素材分析。

全局素材上传控制器，处理文件上传、文件夹上传、上传恢复、进度、失败重试和素材分析。

组件定位

页面级上传控制器，负责监听业务事件、调起上传、维护上传队列，并在上传完成后刷新素材。

全局上传失败重试素材刷新

强依赖

依赖 SharedWorker、Uppy、OSS token、素材创建接口和事件总线。普通静态页面不建议直接接入。

SharedWorkerUppyOSS

接入速览

什么时候用

页面需要统一处理素材上传、文件夹上传、失败重试、上传恢复和上传完成后的素材刷新时使用。

最少必填

EveryWhereUpload 通常只需要挂在页面根部并传入 eventBus；上传入口用 AssetUpload。

返回什么

AssetUpload.action 返回 File[] 和可选文件夹名；上传完成后通过事件刷新素材列表。

上传数据事件协议

容易漏什么

需要 SharedWorker、OSS token、素材创建接口；仅放上传按钮不能完成完整上传链路。

upload-manager工程前置条件

前置条件

条件	说明
SharedWorker	上传管理依赖 SharedWorker
Uppy	通过 @mbjia/upload-manager 使用
登录态	需要 token 和用户信息
素材接口	需要 OSS token、创建素材、目录等接口
事件总线	外部通过事件触发上传流程

流程预览

选择文件/文件夹→文件类型与大小校验

校验结果

不合格：失败列表/提示合格：获取 OSS Token→Uppy + SharedWorker 上传→生成封面/读取时长

创建素材记录→刷新目录和素材列表→emit some-asset-upload-success

效果预览

上传列表3 个文件

video-demo.mp4 上传中 62%

上传进度

展示上传队列、当前进度、失败重试和素材创建后的刷新状态。

引入

import { EveryWhereUpload } from '@mbjia/components'
import { eventBus } from '@mbjia/utils'

<EveryWhereUpload eventBus={eventBus} />

AssetUpload

AssetUpload 是一个上传入口，用于选择文件或文件夹。

import { AssetUpload } from '@mbjia/components'

<AssetUpload
  accept="image/*,video/*"
  action={(files, folderName) => console.log(files, folderName)}
>
  <button>上传素材</button>
</AssetUpload>

interface IUpload {
  action: (files: File[], folderName?: string) => void
  accept: string
  style?: React.CSSProperties
  disAbled?: boolean
  dirAction?: (res: File[]) => void
  className?: string
  onUploadClickCallback?: () => void
}

AssetUpload 回调出参

回调	出参	说明
action	files: File[], folderName?: string	选择文件或文件夹后触发。
dirAction	res: File[]	文件夹选择后的回调。
onUploadClickCallback	无	点击上传入口时触发。

AssetUploadPreset

AssetUploadPreset 是带 hover 浮层的上传入口。外部传入按钮或任意节点，hover 后展示“选择素材/选择文件夹”菜单。

<AssetUploadPreset
  accept="image/*,video/*"
  position="bottom center"
  action={(files, folderName) => upload(files, folderName)}
>
  <button>上传</button>
</AssetUploadPreset>

Props 继承 AssetUpload，额外支持：

字段	类型	必填	默认值	说明
children	React.ReactNode	是	-	触发上传菜单的节点。
position	string	否	'bottom center'	Popup 展示位置。

UploadFailModal

上传失败列表弹窗。用于展示格式、大小、时长等校验失败原因，并根据用户会员状态展示“升级会员”或“联系我们”。

<UploadFailModal
  list={failList}
  type="video"
  supportedType={['mp3', 'wav', 'aac']}
  modelMaxSize={5120}
  onClose={() => setFailList([])}
/>

数据结构：

type UploadFailItem = {
  name: string
  file: File
  type: string
  status: 1 | 0
  reason: string
  url: string
  assetType?: string | number
}

Props：

字段	类型	必填	默认值	说明
list	UploadFailItem[]	是	-	上传失败列表。list.length > 0 时弹窗打开。
onClose	() => void	是	-	关闭弹窗，通常清空失败列表。
title	string	否	'文件上传失败'	弹窗标题。
type	string	否	'video'	失败提示类型，源码内区分 music 和 video。
supportedType	string[]	否	['mp3', 'wav', 'aac']	音乐上传支持格式展示。
modelMaxSize	number | string	否	从权益接口获取	最大上传大小，单位 MB。
isSuiXinCut	boolean	否	false	随心剪场景会额外提示音乐时长需 10s 以上。

依赖：

依赖	用途
reqUserRight	获取会员等级和最大上传大小。
useFetchManagerQrCode	大客户/会员联系客户经理二维码。
getVideoCover / file2base64	生成失败列表预览图。
vip:modal:open	免费用户点击升级时触发会员弹窗。

上传元数据

type SXMeta = {
  uploadingItemId: string
  uploadType?: string
  dir?: string
  dirName?: string
  handle?: FileSystemFileHandle
  rotate?: boolean
  analysis?: boolean
  createAsset?: boolean
  waitForTranscoding?: boolean
  errorStatus?: number
  status?: number
  assetId?: string
  id?: string
  asset?: any
  error?: any
  hide?: number
}

目录上传状态：

export type Folder = {
  folderName: string
  children: (File | Folder)[]
}

export type Dir = (File | Folder)[]

export interface UploadItemType {
  uploadingItemId: string
  file: File
  folderId?: string
  rotate?: boolean
  analysis?: boolean
  preview?: string
  createAsset?: boolean
}

export interface UploadDirState {
  dir: Dir
  dirLevels: {
    folderName: string
    parentName: string | null
  }[][]
  filesBylevel: (UploadItemType & {
    parentFolderName: string | null
  })[][]
  uploading: boolean
  uploadLevel: number
  totalLevels: number
  rootDir: {
    id: string
    name: string | undefined
  } | undefined
}

字段	类型	说明
dir	Dir	原始目录树。
dirLevels	{ folderName; parentName }[][]	按层级拆分后的目录结构。
filesBylevel	UploadItemType[][]	按层级拆分后的文件上传项。
uploading	boolean	是否正在进行文件夹上传。
uploadLevel	number	当前上传层级。
totalLevels	number	总层级数。
rootDir	{ id; name } | undefined	根目录创建后的目录信息。

常用事件

事件	方向	说明
global:everywhereUpload	on	外部触发上传
global:retryUpload	on	重试上传
global:handleCancelUpload	on	取消上传
some-asset-upload-success	emit	上传成功
global:freshFolderList	emit	刷新目录
global:uploadDir	emit/on	上传文件夹
global:selectedFolder	emit/on	已选择目标文件夹

注意事项

• 生产混剪项目需要配置 process.env.sharedWorkerPath。
• 文件夹上传会处理层级限制。
• 素材分析和自动旋转会影响上传后的业务流程。