Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-uploader` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-uploader
bunx cap sync

Importieren

import { Uploader } from '@capgo/capacitor-uploader';

Quickstart

Starte einen Upload, abonniere events, und verfolge den zurückgegebenen Upload id.

import { Uploader } from '@capgo/capacitor-uploader';

let uploadId = '';

const listener = await Uploader.addListener('events', async (event) => {
  if (event.id !== uploadId) return;

  if (event.name === 'uploading') {
    console.log(event.payload.percent);
  }

  if (event.name === 'completed' || event.name === 'failed') {
    if (event.eventId) {
      await Uploader.acknowledgeEvent({ eventId: event.eventId });
    }
    await listener.remove();
  }
});

const { id } = await Uploader.startUpload({
  filePath: 'file:///data/user/0/.../scan.jpg',
  serverUrl: 'https://api.example.com/v1/assets',
  method: 'POST',
  headers: { Authorization: 'Bearer token' },
  maxRetries: 3,
});
uploadId = id;

Beispiel: presigned S3 PUT

PUT Uploads unterstützen nur eine Datei. Nutze die presigned URL als serverUrl und setze method: 'PUT'.

await Uploader.startUpload({
  filePath: capturedUri,
  serverUrl: presignedUrl,
  method: 'PUT',
  headers: { 'Content-Type': 'image/jpeg' },
});

Beispiel: Multipart-Form mit Zusatzfeldern

await Uploader.uploadMultipart({
  url: 'https://api.example.com/upload',
  filePath: localPath,
  fieldName: 'file',
  fields: { userId: '42', kind: 'receipt' },
  headers: { Authorization: 'Bearer token' },
});

Häufige Stolperfallen

• Mehrere Dateien: nutze das files Array in startUpload für einen Multipart-Request. PUT kann nicht mehrere Bodies senden.
• Web-Hintergrund: Uploads stoppen, wenn der Nutzer den Tab schließt. Nutze native Plattformen, wenn der Abschluss App-Backgrounding überleben muss.
• Abbrechen: aufrufen removeUpload({ id }) mit der ID von startUpload.
• Fortschritt: hänge immer den events Listener an, bevor du startest, sonst kannst du frühen Fortschritt verpassen.

API Übersicht

startUpload

Einen Datei-Upload auf einen Server starten.

Der Upload läuft im Hintergrund weiter, selbst wenn die App geschlossen oder in den Hintergrund geschoben wird. Nutze Upload-Events, um Fortschritt, Abschluss oder Fehler zu tracken.

import { Uploader } from '@capgo/capacitor-uploader';

const { id } = await Uploader.startUpload({
  filePath: 'file:///path/to/file.jpg',
  serverUrl: 'https://example.com/upload',
  headers: {
    'Authorization': 'Bearer token'
  },
  method: 'POST',
  uploadType: 'multipart',
  fileField: 'photo'
});
console.log('Upload started with ID:', id);

removeUpload

Einen laufenden Upload abbrechen und entfernen.

Dies stoppt den laufenden Upload und räumt die Ressourcen auf.

import { Uploader } from '@capgo/capacitor-uploader';

await Uploader.removeUpload({ id: 'upload-123' });

Typreferenz

uploadOption

Konfigurationsoptionen für den Datei-Upload.

export interface uploadOption {
  /**
   * The local file path of the file to upload.
   * Can be a file:// URL or an absolute path.
   *
   * @since 0.0.1
   */
  filePath: string;

  /**
   * The server URL endpoint where the file should be uploaded.
   *
   * @since 0.0.1
   */
  serverUrl: string;

  /**
   * The title of the upload notification shown to the user.
   * Android only.
   *
   * @default 'Uploading'
   * @since 0.0.1
   */
  notificationTitle?: string;

  /**
   * HTTP headers to send with the upload request.
   * Useful for authentication tokens, content types, etc.
   *
   * @since 0.0.1
   * @example
   * ```typescript
   * headers: {
   *   'Authorization': 'Bearer token123',
   *   'X-Custom-Header': 'value'
   * }
   * ```
   */
  headers: {
    [key: string]: string;
  };

  /**
   * The HTTP method to use for the upload request.
   *
   * @default 'POST'
   * @since 0.0.1
   */
  method?: 'PUT' | 'POST';

  /**
   * The MIME type of the file being uploaded.
   * If not specified, the plugin will attempt to determine it automatically.
   *
   * @since 0.0.1
   * @example 'image/jpeg', 'application/pdf', 'video/mp4'
   */
  mimeType?: string;

  /**
   * Additional form parameters to send with the upload request.
   * These will be included as form data in multipart uploads.
   *
   * @since 0.0.1
   */
  parameters?: { [key: string]: string };

  /**
   * The maximum number of times to retry the upload if it fails.
   *
   * @since 0.0.1
   * @default 0
   */
  maxRetries?: number;

  /**
   * The type of upload to perform.
   * - 'binary': Uploads the file as raw binary data in the request body
   * - 'multipart': Uploads the file as multipart/form-data
   *
   * @default 'binary'
   * @since 0.0.2
   */
  uploadType?: 'binary' | 'multipart';

  /**
   * The form field name for the file when using multipart upload type.
   * Only used when uploadType is 'multipart'.
   *
   * @default 'file'
   * @since 0.0.2
   */
  fileField?: string;
}

UploadEvent

Event, das während des Upload-Lifecycles gefeuert wird.

export interface UploadEvent {
  /**
   * The current status of the upload.
   * - 'uploading': Upload is in progress
   * - 'completed': Upload finished successfully
   * - 'failed': Upload encountered an error
   *
   * @since 0.0.1
   */
  name: 'uploading' | 'completed' | 'failed';

  /**
   * Additional data about the upload event.
   *
   * @since 0.0.1
   */
  payload: {
    /**
     * Upload progress percentage from 0 to 100.
     * Only present during 'uploading' events.
     *
     * @since 0.0.1
     */
    percent?: number;

    /**
     * Error message if the upload failed.
     * Only present during 'failed' events.
     *
     * @since 0.0.1
     */
    error?: string;

    /**
     * HTTP status code returned by the server.
     * Present during 'completed' and 'failed' events.
     *
     * @since 0.0.1
     */
    statusCode?: number;
  };

  /**
   * Unique identifier for this upload task.
   *
   * @since 0.0.1
   */
  id: string;
}

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit Mit @capgo/capacitor-uploader für die native Funktionalität bei der Nutzung von @capgo/capacitor-uploader, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.