跳转到主要内容

TypeScript 类型

Dropup 导出的所有类型。

导入类型​

import type {
  DropupFile,
  DropupState,
  DropupActions,
  DropupError,
  UseDropupOptions,
  UseDropupReturn,
  FileStatus,
  DropupStatus,
  ValidationRule,
  ValidationError,
  UploadConfig,
  CustomUploader,
  UploadOptions,
  UploadResult,
} from '@samithahansaka/dropup';

核心类型​

DropupFile​

表示上传队列中的文件。

interface DropupFile {
  /** 唯一标识符 */
  id: string;

  /** 原始浏览器 File 对象 */
  file: File;

  /** 文件名 */
  name: string;

  /** 文件大小(字节) */
  size: number;

  /** MIME 类型 */
  type: string;

  /** 当前上传状态 */
  status: FileStatus;

  /** 上传进度 0-100 */
  progress: number;

  /** 图片的预览 URL (Object URL) */
  preview?: string;

  /** 上传成功后的 URL */
  uploadedUrl?: string;

  /** 原始服务器响应 */
  response?: unknown;

  /** 失败时的错误详情 */
  error?: DropupError;

  /** 自定义元数据 */
  meta?: Record<string, unknown>;
}

FileStatus​

可能的文件状态值。

type FileStatus = 'idle' | 'uploading' | 'complete' | 'error' | 'paused';

DropupState​

拖放区域的当前状态。

interface DropupState {
  /** 文件正在拖放上方 */
  isDragging: boolean;

  /** 拖放的文件通过验证 */
  isDragAccept: boolean;

  /** 拖放的文件未通过验证 */
  isDragReject: boolean;

  /** 任何文件当前正在上传 */
  isUploading: boolean;

  /** 所有文件的平均进度 (0-100) */
  progress: number;

  /** 总体状态 */
  status: DropupStatus;
}

DropupStatus​

总体上传状态。

type DropupStatus = 'idle' | 'uploading' | 'complete' | 'error';

DropupActions​

控制上传器的可用操作。

interface DropupActions {
  /** 开始上传文件 */
  upload: (fileIds?: string[]) => void;

  /** 取消上传 */
  cancel: (fileId?: string) => void;

  /** 移除文件 */
  remove: (fileId: string) => void;

  /** 移除所有文件并重置状态 */
  reset: () => void;

  /** 重试失败的上传 */
  retry: (fileIds?: string[]) => void;

  /** 以编程方式添加文件 */
  addFiles: (files: File[] | FileList) => void;

  /** 更新文件元数据 */
  updateFileMeta: (fileId: string, meta: Record<string, unknown>) => void;
}

DropupError​

上传失败的错误对象。

interface DropupError {
  /** 错误代码 */
  code: string;

  /** 人类可读的消息 */
  message: string;

  /** 原始错误(如果可用) */
  cause?: Error;
}

选项类型​

UseDropupOptions​

hook 的配置选项。

interface UseDropupOptions {
  // 验证
  accept?: string | string[];
  maxSize?: number;
  minSize?: number;
  maxFiles?: number;
  maxWidth?: number;
  maxHeight?: number;
  minWidth?: number;
  minHeight?: number;
  customRules?: ValidationRule[];

  // 行为
  multiple?: boolean;
  disabled?: boolean;
  autoUpload?: boolean;
  generatePreviews?: boolean;

  // 上传
  upload?: UploadConfig | CustomUploader;

  // 回调函数
  onFilesAdded?: (files: DropupFile[]) => void;
  onFileRemoved?: (file: DropupFile) => void;
  onValidationError?: (errors: ValidationError[]) => void;
  onUploadStart?: (file: DropupFile) => void;
  onUploadProgress?: (file: DropupFile, progress: number) => void;
  onUploadComplete?: (file: DropupFile, response: unknown) => void;
  onUploadError?: (file: DropupFile, error: DropupError) => void;
  onAllComplete?: (files: DropupFile[]) => void;
}

UploadConfig​

基于 URL 的上传配置。

interface UploadConfig {
  /** 上传端点 URL */
  url: string;

  /** HTTP 方法 */
  method?: 'POST' | 'PUT' | 'PATCH';

  /** 请求头 */
  headers?: Record<string, string>;

  /** 文件的表单字段名 */
  fieldName?: string;

  /** 包含凭证/cookies */
  withCredentials?: boolean;

  /** 请求超时时间(毫秒) */
  timeout?: number;

  /** 额外的表单数据 */
  data?: Record<string, unknown>;
}

CustomUploader​

自定义上传函数类型。

type CustomUploader = (
  file: DropupFile,
  options: UploadOptions
) => Promise<UploadResult>;

UploadOptions​

传递给自定义上传器的选项。

interface UploadOptions {
  /** 用于取消的 Abort signal */
  signal: AbortSignal;

  /** 进度回调 */
  onProgress: (progress: number) => void;
}

UploadResult​

从上传返回的结果。

interface UploadResult {
  /** 上传的文件 URL */
  url?: string;

  /** 原始服务器响应 */
  response?: unknown;
}

验证类型​

ValidationRule​

自定义验证函数。

type ValidationRule = (file: File) =>
  | boolean
  | string
  | Promise<boolean | string>;

返回值:

  • true - 验证通过
  • false - 验证失败(通用错误)
  • string - 验证失败并带有自定义消息

ValidationError​

文件的验证错误。

interface ValidationError {
  /** 验证失败的文件 */
  file: File;

  /** 错误消息数组 */
  errors: string[];
}

返回类型​

UseDropupReturn​

hook 的完整返回类型。

interface UseDropupReturn {
  /** 文件数组 */
  files: DropupFile[];

  /** 当前状态 */
  state: DropupState;

  /** 可用操作 */
  actions: DropupActions;

  /** 拖放区域的 props getter */
  getDropProps: <E extends HTMLElement = HTMLDivElement>(
    props?: React.HTMLAttributes<E>
  ) => DropZoneProps<E>;

  /** input 元素的 props getter */
  getInputProps: (
    props?: React.InputHTMLAttributes<HTMLInputElement>
  ) => InputProps;

  /** 以编程方式打开文件对话框 */
  openFileDialog: () => void;
}

DropZoneProps​

由 getDropProps 返回的 props。

interface DropZoneProps<E extends HTMLElement>
  extends React.HTMLAttributes<E> {
  onDragEnter: React.DragEventHandler<E>;
  onDragOver: React.DragEventHandler<E>;
  onDragLeave: React.DragEventHandler<E>;
  onDrop: React.DragEventHandler<E>;
  onClick: React.MouseEventHandler<E>;
  role: string;
  tabIndex: number;
}

InputProps​

由 getInputProps 返回的 props。

interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  type: 'file';
  accept?: string;
  multiple?: boolean;
  onChange: React.ChangeEventHandler<HTMLInputElement>;
  style: React.CSSProperties;
}

云类型​

S3UploaderConfig​

S3 上传器的配置。

interface S3UploaderConfig {
  getPresignedUrl: (file: DropupFile) => Promise<PresignedUrlResponse>;
}

interface PresignedUrlResponse {
  url: string;
  fields?: Record<string, string>;
}

GCSUploaderConfig​

Google Cloud Storage 上传器的配置。

interface GCSUploaderConfig {
  getSignedUrl: (file: DropupFile) => Promise<SignedUrlResponse>;
}

interface SignedUrlResponse {
  url: string;
  headers?: Record<string, string>;
}

AzureUploaderConfig​

Azure Blob Storage 上传器的配置。

interface AzureUploaderConfig {
  getSasUrl: (file: DropupFile) => Promise<SasUrlResponse>;
}

interface SasUrlResponse {
  url: string;
  headers?: Record<string, string>;
}

分块上传类型​

ChunkedUploaderConfig​

分块上传的配置。

interface ChunkedUploaderConfig {
  /** 上传端点 URL */
  url: string;

  /** 块大小(字节) (默认: 5MB) */
  chunkSize?: number;

  /** 最大并发块数 */
  concurrency?: number;

  /** 请求头 */
  headers?: Record<string, string>;
}

图片处理类型​

CompressOptions​

图片压缩选项。

interface CompressOptions {
  /** 最大宽度 */
  maxWidth?: number;

  /** 最大高度 */
  maxHeight?: number;

  /** 质量 0-1 (默认: 0.8) */
  quality?: number;

  /** 输出格式 */
  type?: 'image/jpeg' | 'image/png' | 'image/webp';
}

类型工具​

泛型类型​

// 提取文件状态
type IdleFile = DropupFile & { status: 'idle' };
type UploadingFile = DropupFile & { status: 'uploading' };
type CompletedFile = DropupFile & { status: 'complete' };
type FailedFile = DropupFile & { status: 'error' };

// 类型守卫函数
function isIdle(file: DropupFile): file is IdleFile {
  return file.status === 'idle';
}

function isUploading(file: DropupFile): file is UploadingFile {
  return file.status === 'uploading';
}

function isComplete(file: DropupFile): file is CompletedFile {
  return file.status === 'complete';
}

function isFailed(file: DropupFile): file is FailedFile {
  return file.status === 'error';
}

使用类型守卫​

const { files } = useDropup();

// 使用类型安全过滤
const uploadingFiles = files.filter(isUploading);
// uploadingFiles 是 UploadingFile[]

const completedFiles = files.filter(isComplete);
// completedFiles 是 CompletedFile[]
编辑此页
最后更新 于 由 Samitha Widanage