Uploader 上传 #

/**
 * 文件读取的结果类型
 * @description 值为`file`时返回文件的`File`对象，值为`dataUrl`时返回文件对应的base64编码
 */
export type FileReadType = 'file' | 'dataUrl';

export type HttpMethod =
  | 'POST'
  | 'GET'
  | 'PUT'
  | 'OPTION'
  | 'PATCH'
  | 'post'
  | 'get'
  | 'put'
  | 'option'
  | 'patch';

/**
 * 文件条目
 */
export interface FileItem {
  /** 文件名称 */
  name?: string;

  /** 原始文件对象 */
  rawFile?: File;

  /** base64格式的文件内容 */
  dataUrl?: string;

  /** 原始文件的MIME类型 */
  type?: string;

  /** 文件的大小 (Bytes) */
  size?: number;

  /** 上次修改时间 */
  lastModified?: number;
}

/**
 * 上传文件条目
 */
export interface UploadFileItem extends FileItem {
  /**
   * 文件名称
   * @description 根据文件的后缀名判断文件类型
   */
  name?: string;

  /** 文件的预览图片的地址 */
  thumbnailUrl?: string;

  /** 文件的下载地址 */
  url?: string;

  /** 文件的上传时间 */
  uploadTime?: string;

  /** 文件的大小 (Bytes) */
  size?: number;

  /**
   * 文件上传状态
   * @description 上传成功、上传失败、上传中、等待上传
   */
  status?: 'success' | 'fail' | 'progress' | 'waiting';

  /**
   * 文件上传进度
   * @description 上传进度百分比，[0, 100]
   */
  percent?: number;

  /**
   * 文件ID
   * @description 用于在文件名称重复时唯一标识一个文件，允许为空
   */
  id?: string;

  /** 用户自定义的上下文数据 */
  [key: string]: any;
}

/**
 * 文件上传进度变更信息
 */
export interface UploadProgressContext {
  /** 上传进度类型 */
  type: 'real' | 'mock';

  /**
   * 相关文件
   * @description 如果单请求上传多个文件，则长度大于一
   */
  files: UploadFileItem[];

  /** 百分比进度值 */
  percent: number;

  [key: string]: any;
}

/**
 * 上传请求响应数据
 * @description 后端上传接口响应的数据
 */
export interface UploadResponseData {
  /**
   * 错误信息
   * @description 如果本字段非空，则认为文件上传失败了
   */
  error?: string;

  /**
   * 上传后的文件访问地址
   * @description 将被赋值给对应文件的`url`字段（单请求上传多个文件`singleRequestUpload=true`时无效）
   */
  url?: string;

  /**
   * 上传后的文件缩略图地址
   * @description 将被赋值给对应文件的`thumbnailUrl`字段（单请求上传多个文件`singleRequestUpload=true`时无效）
   */
  thumbnailUrl?: string;

  [key: string]: any;
}

/**
 * 单个文件上传结果的上下文
 */
export interface UploadResponseContext {
  /**
   * 上传的文件
   */
  file: UploadFileItem;

  /**
   * 是否上传成功
   */
  success: boolean;

  /**
   * 上传请求的响应数据
   * @description 如果是单请求上传多个文件的模式（`singleRequestUpload=true`时），则该字段为空
   */
  responseData?: UploadResponseData;
}

/**
 * 自定义文件上传上下文
 * @description 当用户自定义文件上传方法时，可以通过本上下文中的回调方法通知文件的上传状态
 */
export interface CustomUploadFileContext {
  /** 待上传的文件 */
  file: UploadFileItem;

  /**
   * 更新上传进度回调
   * @description 用于更新当前文件的上传进度
   */
  onProgress: (e: { percent: number } & Record<string, any>) => void;

  /**
   * 上传成功回调
   * @description 文件上传成功后回调，允许将请求响应数据作为参数
   */
  onSuccess: (e?: UploadResponseData) => void;

  /**
   * 上传失败回调
   * @description 文件上传失败后回调，允许将请求响应数据作为参数
   */
  onFail: (e?: UploadResponseData) => void;
}

export interface UploadResult {
  /**
   * 单请求多文件上传的响应数据
   * @description 上传请求的响应数据，仅当单请求上传多个文件`singleRequestUpload=true`时非空
   */
  responseData?: UploadResponseData;

  /**
   * 上传成功的文件及其响应数据
   * @description 如果没有文件上传成功，则为空
   */
  successItems?: UploadResponseContext[];

  /**
   * 上传失败的文件及其响应数据
   * @description 如果没有文件上传失败，则为空
   */
  failedItems?: UploadResponseContext[];
}

/**
 * 内建的列表样式
 * @description `文件详情列表`或者`图片列表`
 */
export type UploaderListType = 'details' | 'image-card';

/**
 * 文件选取参数
 */
export interface FilePickerOption {
  /**
   * 接受上传的文件类型
   * @description 默认不限制
   */
  accept?: string;

  /**
   * 是否启用文件多选
   * @description 是否允许用户一次选择多个文件
   */
  multiple?: boolean;

  /**
   * 文件读取的结果类型
   * @description 用户选择的文件将被转化为本字段所指定的格式
   */
  fileReadType?: FileReadType;

  /** 单个文件的大小限制 (Bytes) */
  maxSize?: number;

  /**
   * 最大文件数量
   * @description 最多可以上传多少个文件
   */
  maxCount?: number;

  /**
   * 已上传文件的数量
   * @description 已经上传了多少个文件，用`maxCount - uploadedFileCount`可以得到还能上传的最大文件数量
   */
  uploadedFileCount?: number;

  [key: string]: any;
}

/**
 * 上传组件上下文
 * @description 组件的相关属性，只读
 */
export interface UploaderContext extends FilePickerOption {
  /** 文件列表的内建样式 */
  listType?: UploaderListType;

  /** 组件是否处于只读状态 */
  readonly?: boolean;

  /** 组件是否处于禁用状态 */
  disabled?: boolean;

  /** 接受上传的文件类型 */
  accept?: string;

  /** 是否启用文件多选 */
  multiple?: boolean;

  /** 文件读取的结果类型 */
  fileReadType?: FileReadType;

  /** 单个文件的大小限制 (Bytes) */
  maxSize?: number;

  /** 最大文件数量 */
  maxCount?: number;

  /** 已上传文件的数量 */
  uploadedFileCount?: number;

  /** 当前显示的文件列表 */
  displayFiles?: UploadFileItem[];
}

/**
 * 自定义文件获取方式
 */
export interface FilePickerItem {
  /**
   * 方式编号
   * @description 唯一标识，不可重复
   */
  key: string;

  /**
   * 显示的名称
   */
  name?: string | ((context: UploaderContext, customOptions: Record<string, any>) => string);

  /**
   * 文件获取的实现方法
   * @description 当用户选择本方式后，将调用本方法来获取文件。
   * 如果`handler`字段为空，且不存在默认配置，则用户选择此方式后将通过h5方式选取文件。
   */
  handler?: (context: UploaderContext, customOptions: Record<string, any>) => Promise<FileItem[]>;

  /**
   * 是否显示
   * @description 如果本方式仅部分平台支持，则应该根据平台的能力决定是否显示本方式
   */
  visible?: boolean | ((context: UploaderContext, customOptions: Record<string, any>) => boolean);

  /**
   * 提示文本
   * @description 显示在名称下方的一行文本
   */
  tip?: string | ((context: UploaderContext, customOptions: Record<string, any>) => string);

  /**
   * 自定义选项
   * @description 一般不需要配置
   */
  customOptions?: Record<string, any>;
}

/** 文件条目的上下文数据 */
export interface FileItemContext {
  /** 被选中的文件 */
  file: UploadFileItem;

  /** 被选中文件在文件列表中的下标 */
  index: number;

  /** 文件列表 */
  fileList: UploadFileItem[];

  /** 上传组件的上下文 */
  uploaderContext: UploaderContext;
}

/**
 * 文件条目的上下文菜单项
 */
export interface FileContextMenuItem {
  /**
   * 选项编号
   * @description
   * 唯一标识，不可重复。
   * 1. 当`key='preview'`时，点击选项将触发预览，组件将执行默认的预览操作（可通过`preventDefaultPreview`禁用）并抛出预览事件；
   * 2. 当`key='delete'`时，点击选项将触发删除，组件将向外抛出删除事件；
   * 3. 当`key`等于其它值时，没有默认行为，需要用户通过`handler`方法自定义实现。
   */
  key: 'preview' | 'delete' | string;

  /**
   * 显示的名称
   */
  name?: string | ((context: FileItemContext, customOptions: Record<string, any>) => string);

  /**
   * 选项行为的实现方法
   * @description 当用户选择本选项后，将调用本方法
   */
  handler?: (context: FileItemContext, customOptions: Record<string, any>) => boolean;

  /**
   * 是否显示
   * @description 默认显示，可以用来隐藏不被支持的选项
   */
  visible?: boolean | ((context: FileItemContext, customOptions: Record<string, any>) => boolean);

  /**
   * 是否禁用
   * @description 默认不禁用，当回调方法返回`true`或非空字符串时禁用，返回的字符串将被作为提示文本显示在名称下方，具有比`tip`更高的优先级
   */
  disabled?:
    | boolean
    | ((context: FileItemContext, customOptions: Record<string, any>) => boolean | string);

  /**
   * 提示文本
   * @description 显示在名称下方的一行文本
   */
  tip?: string | ((context: FileItemContext, customOptions: Record<string, any>) => string);

  /**
   * 自定义选项
   * @description 一般不需要配置
   */
  customOptions?: Record<string, any>;
}

/**
 * 弹层的类型
 * @description 文件选取动作列表、文件条目上下文菜单的动作列表、文件条目上下文菜单的`tooltip`
 */
export enum UploaderPopupType {
  FilePickerActionSheet = 'FilePickerActionSheet',
  ContextMenuActionSheet = 'ContextMenuActionSheet',
  ContextMenuTooltip = 'ContextMenuTooltip'
}

/**
 * 上传文件列表变更上下文
 */
export interface FileListUpdateContext {
  /**
   * 变更来源
   * @description
   * 1. `add` 上传后新增文件
   * 2. `delete` 点击删除按钮或者上下文菜单中的删除选项后删除文件
   */
  trigger: 'add' | 'delete';
}

/** 文件上传前校验参数 */
export interface BeforeUploadValidationParam {
  /** 待上传的（需要校验的）文件列表 */
  files: FileItem[];
  /** 已上传的文件列表 */
  uploadedFiles?: UploadFileItem[];
  /** 文件数量上限 */
  maxCount?: number;
  /** 单个文件的大小上限 */
  maxSize?: number;
  /** 是否允许重名文件 */
  allowDuplicateFile?: boolean;
  /** 单个文件上传前回调 */
  beforeUpload?: (file: UploadFileItem, context: any) => boolean | Promise<boolean>;
  /** 上下文 */
  context?: any;
}

/** 文件条目长按事件默认行为 */
export enum FileItemLongPressAction {
  /** 不进行默认处理 */
  None = 'None',

  /** 通过下方弹出的动作列表显示自定义的上下文菜单 */
  ShowMenu = 'ShowMenu',

  /** 通过`Tooltip`组件显示自定义的上下文菜单 */
  ShowMenuInTooltip = 'ShowMenuInTooltip'
}

/** 校验发现问题的类型 */
export enum FileValidationProblemType {
  SingleFileOverSizeLimit = 'SingleFileOverSizeLimit',
  FileListOverLengthLimit = 'FileListOverLengthLimit',
  DuplicateFileNames = 'DuplicateFileNames',
  BeforeUploadCallback = 'BeforeUploadCallback'
}

/** 校验发现的问题 */
export interface FileValidationProblem {
  /** 问题类型 */
  type: FileValidationProblemType;

  /**
   * 相关的文件列表
   * @description
   * 1. 当`type="SingleFileOverSizeLimit"`时，是本次所选文件中所有超过单文件大小上限的文件；
   * 2. 当`type="FileListOverLengthLimit"`时，是本次所选的所有文件；
   * 3. 当`type="DuplicateFileNames"`时，是本次所选的文件中所有重名的文件；
   * 4. 当`type="BeforeUploadCallback"`时，是本次所选的文件中所有未通过`beforeUpload`自定义校验的文件。
   */
  files: UploadFileItem[];
}

/** 文件上传前校验结果 */
export interface BeforeUploadValidationResult {
  /** 通过校验的文件列表 */
  validFiles: UploadFileItem[];

  /** 检测到的问题列表 */
  problems?: FileValidationProblem[];

  /**
   * 校验参数
   * @description 包含本次校验的上下文参数，禁止修改
   */
  validationParam: BeforeUploadValidationParam;
}