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-file-compressor` 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-file-compressor
bunx cap sync

Importieren

import { FileCompressor } from '@capgo/capacitor-file-compressor';

Quickstart

import { FileCompressor } from '@capgo/capacitor-file-compressor';

const result = await FileCompressor.compressImage({
  path: photoUri,
  width: 1280,
  quality: 0.8,
  mimeType: 'image/jpeg',
});

await uploadFile(result.path);

Beispiel: Web Blob Input

const result = await FileCompressor.compressImage({
  blob: pickedFile,
  quality: 0.75,
  width: 1024,
  mimeType: 'image/webp',
});

Häufige Stolperfallen

• Kein Upscaling: Dimensionen werden nur bei großen Bildern verkleinert.
• PNG-Größe: PNG hat keinen Qualitätsregler; die Ausgabe kann größer als die Quelle sein.
• EXIF: Metadaten werden entfernt; verlassen Sie sich nach der Komprimierung nicht auf Orientierungs-Tags.

API Übersicht

compressImage

Komprimiert eine Bilddatei mit festgelegten Dimensionen und Qualitätseinstellungen.

Diese Methode komprimiert Bilder, um die Dateigröße bei akzeptabler Qualität zu reduzieren. Sie unterstützt Resizing und Formatkonvertierung (JPEG/WebP, plattformabhängig).

Wichtige Hinweise:

• EXIF-Metadaten werden bei der Komprimierung auf allen Plattformen entfernt
• Das Seitenverhältnis bleibt automatisch erhalten, wenn nur eine Dimension angegeben wird
• Komprimierte Dateien werden auf nativen Plattformen in temporären Verzeichnissen gespeichert

import { FileCompressor } from '@capgo/capacitor-file-compressor';

// Web - Compress from file input
const fileInput = document.getElementById('file') as HTMLInputElement;
const file = fileInput.files[0];
const result = await FileCompressor.compressImage({
  blob: file,
  quality: 0.8,
  width: 1200,
  mimeType: 'image/jpeg'
});
const url = URL.createObjectURL(result.blob);

Typreferenz

CompressImageOptions

Optionen zur Komprimierung eines Bildes.

export interface CompressImageOptions {
  /**
   * The file path of the image to compress.
   *
   * **Platform:** Android, iOS only (not supported on Web)
   *
   * Accepts various path formats:
   * - iOS: `file://` URLs or absolute paths
   * - Android: `content://` URIs, `file://` URLs, or absolute paths
   *
   * @since 7.0.0
   * @example "file:///var/mobile/Containers/Data/Application/image.jpg" // iOS
   * @example "content://com.android.providers.downloads.documents/document/msf%3A1000000485" // Android
   * @example "/storage/emulated/0/Download/photo.png" // Android absolute path
   */
  path?: string;

  /**
   * The file blob of the image to compress.
   *
   * **Platform:** Web only (not supported on iOS/Android)
   *
   * Use this when compressing images from file inputs, fetch responses,
   * or any other Blob source in web applications.
   *
   * @since 7.0.0
   * @example
   * ```typescript
   * // From file input
   * const fileInput = document.getElementById('file') as HTMLInputElement;
   * const blob = fileInput.files[0];
   * ```
   * @example
   * ```typescript
   * // From fetch
   * const response = await fetch('https://example.com/image.jpg');
   * const blob = await response.blob();
   * ```
   */
  blob?: Blob;

  /**
   * The quality of the compressed image.
   *
   * **Range:** 0.0 to 1.0
   * - `0.0` = Maximum compression (lowest quality, smallest file)
   * - `1.0` = Minimum compression (highest quality, largest file)
   * - `0.6` = Default balanced compression
   *
   * **Platform:** All platforms
   *
   * Higher quality values result in larger files but better visual quality.
   * The actual compression ratio depends on the image content and format.
   *
   * @since 7.0.0
   * @default 0.6
   * @example 0.8 // High quality
   * @example 0.5 // Medium quality, smaller file
   * @example 0.3 // Low quality, very small file
   */
  quality?: number;

  /**
   * The width of the compressed image in pixels.
   *
   * **Platform:** All platforms
   *
   * If only width is specified, height is calculated automatically
   * to maintain the original aspect ratio.
   *
   * If both width and height are specified, the image is resized
   * to exact dimensions (may distort if ratio differs).
   *
   * @since 7.0.0
   * @example 1920 // Full HD width
   * @example 1200 // Common web image width
   * @example 800  // Mobile-optimized width
   */
  width?: number;

  /**
   * The height of the compressed image in pixels.
   *
   * **Platform:** All platforms
   *
   * If only height is specified, width is calculated automatically
   * to maintain the original aspect ratio.
   *
   * If both width and height are specified, the image is resized
   * to exact dimensions (may distort if ratio differs).
   *
   * @since 7.0.0
   * @example 1080 // Full HD height
   * @example 800  // Common web image height
   * @example 600  // Mobile-optimized height
   */
  height?: number;

  /**
   * The MIME type of the compressed output image.
   *
   * **Platform Support:**
   * - **iOS:** `image/jpeg` only
   * - **Android:** `image/jpeg`, `image/.webp`
   * - **Web:** `image/jpeg`, `image/.webp`
   *
   * **Format Characteristics:**
   * - **JPEG:** Universal support, good for photos, no transparency
   * - **WebP:** Better compression, supports transparency, not on iOS
   *
   * @since 7.0.0
   * @default "image/jpeg"
   * @example "image/jpeg" // JPEG format (all platforms)
   * @example "image/.webp" // WebP format (Android/Web only)
   */
  mimeType?: string;
}

CompressImageResult

Das Ergebnis der Bildkomprimierung.

export interface CompressImageResult {
  /**
   * The file path of the compressed image.
   *
   * **Platform:** Android, iOS only (undefined on Web)
   *
   * Points to a temporary file containing the compressed image.
   * On iOS, typically in `NSTemporaryDirectory()`.
   * On Android, typically in app cache directory.
   *
   * **Important:** These files may be cleaned up by the OS.
   * Copy to permanent storage if needed for long-term use.
   *
   * @since 7.0.0
   * @example "/var/mobile/Containers/Data/tmp/compressed_abc123.jpg" // iOS
   * @example "/data/user/0/com.app/cache/compressed_xyz789.jpg" // Android
   */
  path?: string;

  /**
   * The blob of the compressed image.
   *
   * **Platform:** Web only (undefined on iOS/Android)
   *
   * A Blob object containing the compressed image data.
   * Can be used to:
   * - Create object URLs for preview: `URL.createObjectURL(blob)`
   * - Upload to server via FormData
   * - Save to IndexedDB or other storage
   * - Convert to base64 with FileReader
   *
   * @since 7.0.0
   * @example
   * ```typescript
   * // Create preview URL
   * const url = URL.createObjectURL(result.blob);
   * imageElement.src = url;
   * ```
   * @example
   * ```typescript
   * // Upload to server
   * const formData = new FormData();
   * formData.append('image', result.blob, 'compressed.jpg');
   * await fetch('/upload', { method: 'POST', body: formData });
   * ```
   */
  blob?: Blob;
}

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 Speicher- und Dateiverwaltung zu planen, verbinde es mit Nutzung von @capgo/capacitor-file-compressor für die native Funktionalität bei der Nutzung von @capgo/capacitor-file-compressor, @capgo/capacitor-data-storage-sqlite für die Implementierungsdetails in @capgo/capacitor-data-storage-sqlite, Mit @capgo/capacitor-data-storage-sqlite für die native Funktionalität in „@capgo/capacitor-data-storage-sqlite verwenden“, @capgo/capacitor-file für das Implementierungsdetail in @capgo/capacitor-file und @capgo/capacitor-file verwenden für die native Funktion bei der Nutzung von @capgo/capacitor-file.