ຂ້າມໄປຫາເນື້ອຫາຫຼັກ

ປະເພດ TypeScript

ປະເພດທັງໝົດທີ່ export ຈາກ 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;

  /** ຂະໜາດໄຟລ໌ເປັນ bytes */
  size: number;

  /** ປະເພດ MIME */
  type: string;

  /** ສະຖານະການອັບໂຫຼດປັດຈຸບັນ */
  status: FileStatus;

  /** ຄວາມຄືບໜ້າການອັບໂຫຼດ 0-100 */
  progress: number;

  /** URL ຕົວຢ່າງສຳລັບຮູບພາບ (Object URL) */
  preview?: string;

  /** URL ຫຼັງການອັບໂຫຼດສຳເລັດ */
  uploadedUrl?: string;

  /** ການຕອບກັບດິບຈາກເຊີບເວີ */
  response?: unknown;

  /** ລາຍລະອຽດຂໍ້ຜິດພາດຖ້າລົ້ມເຫຼວ */
  error?: DropupError;

  /** Metadata ທີ່ກຳນົດເອງ */
  meta?: Record<string, unknown>;
}

FileStatus​

ຄ່າສະຖານະໄຟລ໌ທີ່ເປັນໄປໄດ້.

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

DropupState​

ສະຖານະປັດຈຸບັນຂອງ dropzone.

interface DropupState {
  /** ໄຟລ໌ກຳລັງຖືກລາກຜ່ານ */
  isDragging: boolean;

  /** ໄຟລ໌ທີ່ລາກຜ່ານການກວດສອບ */
  isDragAccept: boolean;

  /** ໄຟລ໌ທີ່ລາກການກວດສອບລົ້ມເຫຼວ */
  isDragReject: boolean;

  /** ໄຟລ໌ໃດໜຶ່ງກຳລັງອັບໂຫຼດ */
  isUploading: boolean;

  /** ຄວາມຄືບໜ້າສະເລ່ຍຂອງໄຟລ໌ທັງໝົດ (0-100) */
  progress: number;

  /** ສະຖານະໂດຍລວມ */
  status: DropupStatus;
}

DropupStatus​

ສະຖານະການອັບໂຫຼດໂດຍລວມ.

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

DropupActions​

Actions ທີ່ມີຢູ່ເພື່ອຄວບຄຸມ uploader.

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;

  /** ອັບເດດ metadata ໄຟລ໌ */
  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;

  // Callbacks
  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';

  /** Request headers */
  headers?: Record<string, string>;

  /** ຊື່ຟີລ form ສຳລັບໄຟລ໌ */
  fieldName?: string;

  /** ລວມ credentials/cookies */
  withCredentials?: boolean;

  /** Request timeout ເປັນ milliseconds */
  timeout?: number;

  /** ຂໍ້ມູນ form ເພີ່ມເຕີມ */
  data?: Record<string, unknown>;
}

CustomUploader​

ປະເພດຟັງຊັນການອັບໂຫຼດທີ່ກຳນົດເອງ.

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

UploadOptions​

ຕົວເລືອກທີ່ສົ່ງໃຫ້ custom uploader.

interface UploadOptions {
  /** Abort signal ສຳລັບການຍົກເລີກ */
  signal: AbortSignal;

  /** Callback ຄວາມຄືບໜ້າ */
  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 ທີ່ມີຢູ່ */
  actions: DropupActions;

  /** Props getter ສຳລັບພື້ນທີ່ວາງ */
  getDropProps: <E extends HTMLElement = HTMLDivElement>(
    props?: React.HTMLAttributes<E>
  ) => DropZoneProps<E>;

  /** Props getter ສຳລັບອົງປະກອບ input */
  getInputProps: (
    props?: React.InputHTMLAttributes<HTMLInputElement>
  ) => InputProps;

  /** ເປີດ dialog ໄຟລ໌ດ້ວຍໂປຣແກຣມ */
  openFileDialog: () => void;
}

DropZoneProps​

Props ທີ່ສົ່ງຄືນໂດຍ getDropProps.

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​

Props ທີ່ສົ່ງຄືນໂດຍ getInputProps.

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

ປະເພດຄລາວ​

S3UploaderConfig​

ການຕັ້ງຄ່າສຳລັບ S3 uploader.

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

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

GCSUploaderConfig​

ການຕັ້ງຄ່າສຳລັບ Google Cloud Storage uploader.

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

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

AzureUploaderConfig​

ການຕັ້ງຄ່າສຳລັບ Azure Blob Storage uploader.

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

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

ປະເພດການອັບໂຫຼດແບບແບ່ງສ່ວນ​

ChunkedUploaderConfig​

ການຕັ້ງຄ່າສຳລັບການອັບໂຫຼດແບບແບ່ງສ່ວນ.

interface ChunkedUploaderConfig {
  /** URL ຈຸດໝາຍປາຍທາງການອັບໂຫຼດ */
  url: string;

  /** ຂະໜາດສ່ວນເປັນ bytes (ຄ່າເລີ່ມຕົ້ນ: 5MB) */
  chunkSize?: number;

  /** ຈຳນວນສ່ວນທີ່ພ້ອມກັນສູງສຸດ */
  concurrency?: number;

  /** Request headers */
  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' };

// ຟັງຊັນ type guard
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';
}

ການນຳໃຊ້ກັບ Type Guards​

const { files } = useDropup();

// ກັ່ນຕອງດ້ວຍຄວາມປອດໄພທາງປະເພດ
const uploadingFiles = files.filter(isUploading);
// uploadingFiles ແມ່ນ UploadingFile[]

const completedFiles = files.filter(isComplete);
// completedFiles ແມ່ນ CompletedFile[]