Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

bun add @capgo/capacitor-file-compressor
bunx cap sync

Importa

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

Avvio rapido

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);

Esempio: web Blob input

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

Errori comuni

• Nessun upscaling: le dimensioni riducono solo le immagini grandi.
• Dimensione PNG: PNG has no quality knob, output can exceed source size.
• EXIF: i metadati vengono rimossi, non fare affidamento sui tag di orientamento dopo la compressione.

Panoramica API

compressImage

Comprime un file immagine con dimensioni e impostazioni di qualità specificate.

Questo metodo comprime le immagini per ridurne il peso mantenendo una qualità accettabile. Supporta il ridimensionamento e la conversione del formato (JPEG/WebP a seconda della piattaforma).

Note importanti:

• I metadati EXIF vengono rimossi durante la compressione su tutte le piattaforme
• Il rapporto d'aspetto viene mantenuto automaticamente se viene fornita una sola dimensione
• I file compressi vengono salvati in directory temporanee sulle piattaforme native

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);

Riferimento ai tipi

CompressImageOptions

Opzioni per la compressione di un'immagine.

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

Il risultato della compressione di un'immagine.

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;
}

Fonte di verità

Questa pagina è generata dalla src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Continua da Getting Started

Se stai usando Per iniziare per pianificare lo storage e la gestione dei file, connettilo a Utilizzo di @capgo/capacitor-file-compressor per la funzionalità nativa in Utilizzo di @capgo/capacitor-file-compressor, @capgo/capacitor-data-storage-sqlite per i dettagli di implementazione in @capgo/capacitor-data-storage-sqlite, Utilizzo di @capgo/capacitor-data-storage-sqlite per la funzionalità nativa in Utilizzo di @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file per i dettagli di implementazione in @capgo/capacitor-file, e Utilizzo di @capgo/capacitor-file per la funzionalità nativa in Utilizzo di @capgo/capacitor-file.