通用的上传策略

注意

此策略暂未实现，以下为设计文档

在使用扩展 hooks 前，确保你已熟悉了 alova 的基本使用。

简便的文件上传，传入 base64、file 对象、blob 对象、arraybuffer 对象、Canvas 都可以直接上传，内部实现自动转换，使用场景有：

1. 上传组件的样式不符合时
2. 上传数据格式多样时

功能需求

1. 支持单个、多个文件上传，多个文件同时上传时可以同时上传
2. 多个文件上传进度、总进度
3. 自动转换数据格式为 File
4. 失败可手动触发重新上传
5. 限制文件格式和大小
6. 文件数据回显
7. 自动的缩略图（适用于图片）
8. 文件上传总进度

useUploader 的全部参数一览

const {
  fileList, // 文件数据列表，每项包含文件名、文件路径、上传状态、上传进度，具体格式见下面
  file, // 第一个文件数据项，可以使用计算属性，一般用于上传单个文件使用
  loading, // 是否正在上传，boolean 值
  progress, // 上传总进度，具体格式见下面
  appendFiles, // 添加文件数据项（添加后自动转换为 File 对象）
  upload, // 上传操作，传入下标指定哪个项上传（用于错误重试），未传入上传全部未成功的项
  onFilesAppend, // 添加文件事件
  onExceed, // 文件数量被限制事件
  onFormatMismatch, // 文件格式不匹配事件
  onSuccess, // 每个文件上传成功事件
  onError, // 每个文件上传失败事件
  onComplete // 每个文件上传完成事件
} = useUploader(({ file, name }) => uploadFile(file, name), {
  limit: 3, // 限制上传文件
  accept: ['png', 'jpg', 'pdf'], // 接受的自动转换后的文件格式
  imageTempLink: true, // 是否生成临时图片路径，用于在图片上传完成前也可以展示图片内容，默认为 false

  // 设置一个函数，当上传成功时，可以自动将 fileList 项中的 src 字段替换为服务器上的文件地址，在上传图片时常用
  // data 为响应数据，此函数返回服务端的文件地址
  // 如果未指定此函数则不会有替换行为
  replaceSrcFromResponse: data => data.imgPath
});

useUploader 参数的详细格式及解释

参数格式使用 typescript 表示，便于理解

返回的响应式状态

以下都是响应式的值

// file值的格式
interface file {
  src?: string; // 临时路径或上传成功后的文件路径，非图片
  file: File; // File 对象
  status: 0 | 1 | 2 | 3; // 0 表示未上传，1 表示上传中，2 表示已完成， 3 表示上传错误
  error?: Error; // 错误对象，当上传错误时需要将错误对象赋值上去
  progress: {
    loaded: number; // 已上传大小
    total: number; // 文件总大小
  };
}
// fileList值的格式
type fileList = file[];

// loading值的格式
type loading = boolean; // 是否正在上传

// 上传总进度信息
interface progress {
  loaded: number; // 已上传的大小，多个文件叠加
  total: number; // 文件总大小，多个文件叠加
  count: number; // 正在上传的文件总数
  successCount: number; // 已成功上传的文件数
  failCount: number; // 上传失败的文件数
}

返回的操作函数

interface RawFile {
  file?: File | string | Blob | ArrayBuffer | HTMLCanvasElement; // 可以传入 base64、file 对象、blob 对象、arraybuffer，canvas 元素，回显时可不传
  src?: string; // 文件预览地址，如果传了即使 imageTempLink 为 true 也不会覆盖它
  name?: string; // 文件名，file 为非 File 对象时必填，在 new File 时用到
  mimeType?: string; // 内部转换为 File 对象时的文件类型，在 new File 时用到，建议 file 为非 File 对象时传入
  status?: 0 | 1 | 2 | 3; // 0 表示未上传，1 表示上传中，2 表示已完成，3 表示上传失败，不传默认为 0
}

/**
 * 追加上传的文件进去，追加后会自动将列表的 file 项转换为 File 对象，此时 name 必须有值
 */
type appendFiles = (
  files: RawFile | RawFile[], // 单个文件时传对象、多个文件时传数组
  start?: number // 从 fileList 哪个位置开始追加
) => number; // 追加成功的个数，可能因为数量限制、格式限制而追加失败

/**
 * 执行上传操作
 * 如果未传入参数则会自动将 fileList 内所有 file 属性有值的、status 为 0 和 3（未上传和上传失败）的重新发起上传请求
 * 如果传入了参数下标，则将 fileList 对应下标的项重新组成一个数组，也通过上面的条件过滤出可上传的进行上传请求，但此时如果有不符合条件的需要报错，而不是忽略
 *
 * 发起上传操作后：
 * 多个文件的上传将会并行发起上传请求，也就是将符合上传条件的文件数组遍历，依次调用 useUploader 的第一个回调函数获取 Method 对象发送请求，内部可以使用 useRequst 实现，因为 fileList 中有很多属性是在 useRequest 都可以提供
 */
type upload = (...indexes: number[]) => void;

事件绑定函数

每个事件绑定的回调函数都会接收一个事件对象，格式如下

// 触发时机：调用appendFiles添加文件时触发
type onFilesAppend = (handler: (event: AlovaFileEvent) => void) => void;
interface AlovaFileEvent {
  files: file[]; // 符合条件的，并且转换过后的文件数组
  rawFiles: RawFile[]; // 在 appendFiles 中传入的符合条件的数据数组，是还未转换过后的文件数组
  allRawFiles: RawFile[]; // 在 appendFiles 中传入的原数据数组
}

// 触发时机：当调用appendFiles时，文件数量被限制时触发
type onExceed = (handler: (event: AlovaFileExceededEvent) => void) => void;
interface AlovaFileExceededEvent extends AlovaFileEvent {
  exceeded: number; // 超过的数量
  limit: number; // 总限制数量
}

// 触发时机：当调用appendFiles时，有文件格式不匹配时触发
type onFormatMismatch = (handler: (event: AlovaFileMismatchEvent) => void) => void;
interface AlovaFileMismatchEvent extends AlovaFileEvent {
  mismatchFiles: RawFile[]; // 格式不匹配的文件数组
}

// 触发时机：每个文件上传成功时触发，内部可复用useRequest的onSuccess事件
type onSuccess = (handler: (event: AlovaFileSuccessEvent) => void) => void;
interface AlovaFileSuccessEvent extends AlovaSuccessEvent {
  file: file; // 上传成功的文件项
}

// 触发时机：每个文件上传失败时触发，内部可复用useRequest的onError事件
type onError = (handler: (event: AlovaFileErrorEvent) => void) => void;
interface AlovaFileErrorEvent extends AlovaErrorEvent {
  file: file; // 上传失败的文件项
}

// 触发时机：每个文件上传完成时触发，内部可复用useRequest的onComplete事件
type onComplete = (handler: (event: AlovaFileCompleteEvent) => void) => void;
interface AlovaFileCompleteEvent extends AlovaCompleteEvent {
  file: file; // 上传成功的文件项
}

开发指南

开发前请仔细阅读开发指南

开发此 use hook 需要开发以下内容：

1. 在 src/hooks 下编写 useUploader 功能代码
2. useUploader 功能的完整单元测试，建议在 vue 和 react 下测试
3. useUploader 的 typescript 类型声明，需要分别在packages/scene-react/typings/index.d.ts、packages/scene-vue/typings/index.d.ts、packages/scene-svelte/typings/index.d.ts下添加。公共的类型声明可以放在typings/general.d.ts中，打包时会将此文件分别复制到子包的typings文件夹下，也可以手动运行npm run cp:files复制文件夹。