mirror of
https://github.com/transloadit/uppy.git
synced 2026-01-23 02:25:07 +00:00
149 lines
9.2 KiB
Text
149 lines
9.2 KiB
Text
---
|
|
description: Read this when you are about to use the Uppy class from @uppy/core
|
|
globs:
|
|
alwaysApply: false
|
|
---
|
|
# Uppy Core Summary
|
|
|
|
If you need to reference or work with the `Uppy` class from `@uppy/core`, here is an high-level overview of the class.
|
|
|
|
## `Uppy<M extends Meta, B extends Body>` Class
|
|
|
|
A modular file uploader. Manages plugins, state, events, and file handling.
|
|
|
|
**Generics:**
|
|
|
|
* `M`: Metadata object shape associated with files (`Meta`).
|
|
* `B`: Body object shape associated with files (`Body`).
|
|
|
|
**Key Public Properties:**
|
|
|
|
* `opts: NonNullableUppyOptions<M, B>`: The fully resolved Uppy options.
|
|
* `store: Store<State<M, B>>`: The state management store (defaults to `DefaultStore`).
|
|
* `i18n: I18n`: The translation function.
|
|
* `i18nArray: Translator['translateArray']`: The array translation function.
|
|
* `locale: Locale`: The active locale object.
|
|
|
|
**Constructor:**
|
|
|
|
* `constructor(opts?: UppyOptionsWithOptionalRestrictions<M, B>)`
|
|
|
|
**Core Public Methods:**
|
|
|
|
* `use<T extends typeof BasePlugin<any, M, B>>(Plugin: T, ...args: OmitFirstArg<ConstructorParameters<T>>): this`: Adds a plugin instance.
|
|
* `getPlugin<T extends UnknownPlugin<M, B> = UnknownPlugin<M, B>>(id: string): T | undefined`: Retrieves a plugin instance by ID.
|
|
* `iteratePlugins(method: (plugin: UnknownPlugin<M, B>) => void): void`: Executes a function on all installed plugins.
|
|
* `removePlugin(instance: UnknownPlugin<M, B>): void`: Removes a plugin instance.
|
|
* `addFile(file: File | MinimalRequiredUppyFile<M, B>): UppyFile<M, B>['id']`: Adds a single file.
|
|
* `addFiles(fileDescriptors: MinimalRequiredUppyFile<M, B>[]): void`: Adds multiple files.
|
|
* `removeFile(fileID: string): void`: Removes a file by ID.
|
|
* `removeFiles(fileIDs: string[]): void`: Removes multiple files by ID.
|
|
* `getFile(fileID: string): UppyFile<M, B>`: Retrieves a file object by ID.
|
|
* `getFiles(): UppyFile<M, B>[]`: Retrieves all file objects as an array.
|
|
* `setOptions(newOpts: MinimalRequiredOptions<M, B>): void`: Updates Uppy options.
|
|
* `setState(patch?: Partial<State<M, B>>): void`: Updates the Uppy state.
|
|
* `getState(): State<M, B>`: Retrieves the current Uppy state.
|
|
* `setFileState(fileID: string, state: Partial<UppyFile<M, B>>): void`: Updates the state for a specific file.
|
|
* `setMeta(data: Partial<M>): void`: Merges metadata into the global `state.meta` and all file `meta` objects.
|
|
* `setFileMeta(fileID: string, data: Partial<M>): void`: Merges metadata into a specific file's `meta` object.
|
|
* `upload(): Promise<NonNullable<UploadResult<M, B>> | undefined>`: Starts the upload process for all new files.
|
|
* `retryUpload(fileID: string): Promise<UploadResult<M, B> | undefined>`: Retries a failed upload for a specific file.
|
|
* `retryAll(): Promise<UploadResult<M, B> | undefined>`: Retries all failed uploads.
|
|
* `cancelAll(): void`: Cancels all uploads and removes all files.
|
|
* `pauseResume(fileID: string): boolean | undefined`: Toggles pause/resume state for a resumable upload.
|
|
* `pauseAll(): void`: Pauses all resumable uploads.
|
|
* `resumeAll(): void`: Resumes all paused uploads.
|
|
* `info(message: string | { message: string; details?: string | Record<string, string> }, type?: LogLevel, duration?: number): void`: Displays an informational message via UI plugins.
|
|
* `hideInfo(): void`: Hides the oldest info message.
|
|
* `log(message: unknown, type?: 'error' | 'warning'): void`: Logs a message using the configured logger.
|
|
* `on<K extends keyof UppyEventMap<M, B>>(event: K, callback: UppyEventMap<M, B>[K]): this`: Registers an event listener.
|
|
* `off<K extends keyof UppyEventMap<M, B>>(event: K, callback: UppyEventMap<M, B>[K]): this`: Unregisters an event listener.
|
|
* `emit<T extends keyof UppyEventMap<M, B>>(event: T, ...args: Parameters<UppyEventMap<M, B>[T]>): void`: Emits an event.
|
|
* `destroy(): void`: Uninstalls all plugins and cleans up the Uppy instance.
|
|
|
|
**Internal Lifecycle Methods (Called by Uppy):**
|
|
|
|
* `addPreProcessor(fn: Processor): void`
|
|
* `removePreProcessor(fn: Processor): boolean`
|
|
* `addPostProcessor(fn: Processor): void`
|
|
* `removePostProcessor(fn: Processor): boolean`
|
|
* `addUploader(fn: Processor): void`
|
|
* `removeUploader(fn: Processor): boolean`
|
|
|
|
---
|
|
|
|
## Key Associated Types
|
|
|
|
* **`UppyFile<M extends Meta, B extends Body>`**: Represents a file within Uppy.
|
|
* `id: string`: Unique file ID.
|
|
* `source?: string`: Source plugin ID.
|
|
* `name: string`: File name.
|
|
* `type?: string`: MIME type.
|
|
* `data: Blob | File`: The actual file data.
|
|
* `meta: M & { name: string, type: string }`: User and Uppy metadata.
|
|
* `size: number | null`: File size in bytes.
|
|
* `isRemote: boolean`: If the file is from a remote source (Companion).
|
|
* `remote?: { requestClientId: string, ... }`: Remote source details.
|
|
* `progress: FileProgressStarted | FileProgressNotStarted`: Upload progress state.
|
|
* `error?: string`: Error message if upload failed.
|
|
* `isPaused?: boolean`: If upload is paused (for resumable uploads).
|
|
* `isGhost?: boolean`: If file is restored without data (Golden Retriever).
|
|
* `response?: { status: number, body: B, uploadURL?: string, ... }`: Upload response details.
|
|
* `preview?: string`: URL to a preview image.
|
|
* `[key: string]: any`: Extensible with plugin-specific state.
|
|
|
|
* **`State<M extends Meta, B extends Body>`**: The main Uppy state object.
|
|
* `files: { [fileID: string]: UppyFile<M, B> }`: Object map of files by ID.
|
|
* `currentUploads: { [uploadID: string]: CurrentUpload<M, B> }`: Map of active uploads.
|
|
* `capabilities: { uploadProgress: boolean, individualCancellation: boolean, resumableUploads: boolean, ... }`: Detected/configured capabilities.
|
|
* `totalProgress: number`: Overall upload progress (0-100).
|
|
* `meta: M`: Global metadata.
|
|
* `info: Array<{ type: LogLevel, message: string, details?: string | Record<string, string> }>`: Info messages for UI display.
|
|
* `error: string | null`: Global error message.
|
|
* `allowNewUpload: boolean`: Whether new uploads can be started.
|
|
* `plugins: { [pluginID: string]: Record<string, unknown> }`: State managed by plugins.
|
|
* `recoveredState: null | { files: ..., currentUploads: ... }`: State recovered by Golden Retriever.
|
|
|
|
* **`UppyOptions<M extends Meta, B extends Body>`**: Options for the Uppy constructor.
|
|
* `id?: string`: Instance ID (default: 'uppy').
|
|
* `autoProceed?: boolean`: Start upload automatically after files are added (default: false).
|
|
* `allowMultipleUploadBatches?: boolean`: Allow adding files while an upload is in progress (default: true).
|
|
* `debug?: boolean`: Enable debug logging (default: false).
|
|
* `restrictions: Restrictions`: File restrictions (type, size, number).
|
|
* `meta?: M`: Initial global metadata.
|
|
* `onBeforeFileAdded?: (currentFile: UppyFile<M, B>, files: { ... }) => UppyFile<M, B> | boolean | undefined`: Hook before a file is added.
|
|
* `onBeforeUpload?: (files: { ... }) => { ... } | boolean`: Hook before an upload starts.
|
|
* `locale?: Locale`: Custom locale strings.
|
|
* `store?: Store<State<M, B>>`: Custom state store.
|
|
* `logger?: { debug, warn, error }`: Custom logger.
|
|
* `infoTimeout?: number`: Duration for info messages (ms).
|
|
|
|
* **`Restrictions`**: File restriction options.
|
|
* `maxFileSize?: number | null`: Max individual file size (bytes).
|
|
* `minFileSize?: number | null`: Min individual file size (bytes).
|
|
* `maxTotalFileSize?: number | null`: Max total size of all files (bytes).
|
|
* `maxNumberOfFiles?: number | null`: Max number of files allowed.
|
|
* `minNumberOfFiles?: number | null`: Min number of files required.
|
|
* `allowedFileTypes?: string[] | null`: Allowed MIME types or extensions (e.g., `['image/*', '.pdf']`).
|
|
* `requiredMetaFields?: string[]`: Meta fields that must be present before upload.
|
|
|
|
* **`UppyEventMap<M extends Meta, B extends Body>`**: Map of event names to their callback signatures (includes events like `file-added`, `upload-progress`, `upload-success`, `complete`, `error`, `restriction-failed`, etc.).
|
|
|
|
* **`UploadResult<M extends Meta, B extends Body>`**: The object returned when an upload completes.
|
|
* `successful?: UppyFile<M, B>[]`: Array of successfully uploaded files.
|
|
* `failed?: UppyFile<M, B>[]`: Array of files that failed to upload.
|
|
* `uploadID?: string`: The ID of the upload batch.
|
|
|
|
* **`BasePlugin<...> `**: The base class for all Uppy plugins.
|
|
* `id: string`: Unique plugin ID.
|
|
* `type: string`: Plugin type ('acquirer', 'modifier', 'uploader', 'presenter', 'orchestrator', 'logger').
|
|
* `uppy: Uppy<M, B>`: Reference to the Uppy instance.
|
|
* `install(): void`: Called when the plugin is added.
|
|
* `uninstall(): void`: Called when the plugin is removed.
|
|
* `update(state: Partial<State<M, B>>): void`: Called on every Uppy state update.
|
|
|
|
* **`Processor`**: Type for pre/post/upload processor functions `(fileIDs: string[], uploadID: string) => Promise<unknown> | void`.
|
|
|
|
* **`LogLevel`**: `'info' | 'warning' | 'error' | 'success'`.
|
|
|
|
* **`PartialTree`**: Type used by Provider plugins (like Google Drive) to represent folder structures (`(PartialTreeFile | PartialTreeFolder)[]`).
|