Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

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

Importar

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

Inicio rápido

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

Ejemplo: web Blob input

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

Errores comunes

• Sin upscaling: las dimensiones solo reducen imágenes grandes.
• Tamaño PNG: PNG no tiene control de calidad; el output puede superar el tamaño original.
• EXIF: se elimina la metadata; no confíes en los tags de orientación tras comprimir.

Resumen de API

compressImage

Comprime un archivo de imagen con dimensiones y calidad específicas.

Este método comprime imágenes para reducir su tamaño manteniendo una calidad aceptable. Permite cambiar el tamaño y convertir el formato (JPEG/WebP según la plataforma).

Notas importantes:

• Los metadatos EXIF se eliminan durante la compresión en todas las plataformas
• La relación de aspecto se mantiene automáticamente si solo se indica una dimensión
• Los archivos comprimidos se guardan en directorios temporales en plataformas nativas

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

Referencia de tipos

CompressImageOptions

Opciones para comprimir una imagen.

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

El resultado de comprimir una imagen.

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

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el almacenamiento y la gestión de archivos, conéctalo con Uso de @capgo/capacitor-file-compressor para la capacidad nativa en Uso de @capgo/capacitor-file-compressor, @capgo/capacitor-data-storage-sqlite para el detalle de implementación en @capgo/capacitor-data-storage-sqlite, Uso de @capgo/capacitor-data-storage-sqlite para la funcionalidad nativa en Uso de @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file para el detalle de implementación en @capgo/capacitor-file, y Uso de @capgo/capacitor-file para la capacidad nativa en Uso de @capgo/capacitor-file.