青梧 UI

Upload 图片上传

拖拽区 / 按钮两种触发形态,客户端压缩为原图 / WebP / AVIF 多份输出,内置 XHR 字节级真实上传进度,onProgress 实时回调。单文件限制(maxCount: 1)时拖拽容器承载大图预览,URL 导入入口在图片框内,右上角 ✕ 一键清空全部上传项。

操作日志
暂无日志,上传图片后将在此显示
import { ImageUpload } from "@qingwu-ui/upload";
import "@qingwu-ui/upload/style.css";   // 按钮形态样式已内置
useEffect(() => {
  const el = rootRef.current;
  if (!el) return;
  uploaderRef.current = new ImageUpload(el, {
  maxCount: 1,       // 数量上限
  url: "/api/upload",        // 内置 XHR 上传(字节级真实进度)
  onProgress: (item) => console.log(item.progress), // 每项上传进度回调
  });
  return () => uploaderRef.current?.destroy();
}, []);
return <div ref={rootRef} />;

配置项

属性说明类型默认值
trigger触发形态:大拖拽区或小按钮(复用 @qingwu-ui/button 样式)dropzone | buttondropzone
accept接受的类型string[]["image/*"]
supportedFormats图片格式白名单(无点扩展名,如 jpg/png/webp/gif/avif);指定后映射为 input accept 并驱动提示文案string[]全支持
multiple是否允许多选 / 多拖booleantrue
maxCount最多保留的上传项总数,0 表示不限number0
maxSizeMB单文件大小上限(MB)number10
url内置 XHR 上传地址(与 uploadFn 二选一;均不传则仅压缩不上传)string-
fieldNameFormData 字段名string"file"
headers自定义请求头Record<string, string>-
uploadFn自定义上传函数,onProgress 由宿主驱动进度条UploadFn-
urlImportURL 导入入口开关(仅 dropzone 形态)booleantrue
initialUrls编辑态回显:已存在的资源 URL 列表,渲染为成功项(缩略图 + 已上传 + 删除)string[]-
persist持久化策略:未完成的上传项(File + 元数据)存 IndexedDB,刷新后恢复列表并自动重传;成功项不持久化(URL 由宿主经 initialUrls 回显)"session" | "local" | "off""off"
previewFit单文件模式容器大图适配:cover 铺满裁切 / contain 等比例缩小完整显示 / auto 按比例自适应(与容器比例接近铺满,差异大完整显示避免裁切主体)"cover" | "contain" | "auto""cover"
urlImportTimeoutURL 导入单次请求超时(ms)number10000
compress压缩总开关;关闭时仅按原图上传booleantrue
formats输出格式(三选一 / 都要)OutputFormat[]["original","webp","avif"]
quality压缩质量number0.8
maxWidth缩放上限宽度number2048
maxHeight缩放上限高度number2048

事件

属性说明类型默认值
onStart上传项开始上传时触发(item: UploadItem) => void-
onProgress上传进度回调:内置 XHR 为字节级真实进度;uploadFn 模式下由宿主调用 onProgress 驱动(item: UploadItem) => void-
onSuccess上传成功时触发(item: UploadItem) => void-
onError上传失败时触发(item: UploadItem, error: Error) => void-
onChange列表增删时触发;细粒度状态变化请用 onStart / onProgress / onSuccess / onError(items: UploadItem[]) => void-