Getting Started

설치

Capgo의 AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 기능을 추가하려면 다음 명령어를 사용하세요.

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

다음 명령어를 사용하여 다음 프롬프트를 사용하세요.

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

만약 Manual Setup을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래에 플랫폼에 따라 설명된 지침을 따르세요.

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

Import

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

API 개요

compressImage

이미지를 지정된 크기와 품질 설정으로 압축합니다.

이미지의 파일 크기를 줄이면서도 적절한 품질을 유지하기 위해 이미지를 압축합니다. 이 메소드는 리사이즈와 형식 변환 (JPEG/WebP에 따라 플랫폼에 따라)을 지원합니다.

중요한 참고 사항:

• 모든 플랫폼에서 압축 시 EXIF 메타데이터가 제거됩니다.
• 만약 하나의 크기만 제공하면 자동으로 비율이 유지됩니다.
• __CAPGO_KEEP_0__ 파일은 네이티브 플랫폼의 임시 디렉토리에 저장됩니다.

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

__CAPGO_KEEP_0__

CompressImageOptions

이미지 압축에 대한 옵션입니다.

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

이미지 압축 결과입니다.

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

__CAPGO_KEEP_0__

이 페이지는 플러그인의 src/definitions.ts. upstream에서 API이 변경되면 다시 싱크를 실행하세요.

Getting Started에서 계속하세요

Capacitor를 사용 중이라면 Getting Started를 사용하여 저장소 및 파일 처리를 계획하세요. 그것을 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-file-compressor와 연결하세요. @capgo/capacitor-file-compressor의 native 기능을 사용하는 경우 @capgo/capacitor-file-compressor를 사용하세요. @capgo/capacitor-data-storage-sqlite의 implementation detail을 사용하는 경우 @capgo/capacitor-data-storage-sqlite를 사용하세요. @capgo/capacitor-data-storage-sqlite를 사용하세요. @capgo/capacitor-data-storage-sqlite를 사용하세요. @capgo/capacitor-data-storage-sqlite를 사용하세요. 자연스러운 기능을 사용하는 데 @capgo/capacitor-data-storage-sqlite을 사용하세요. @capgo/capacitor-file implementation detail에 대한 정보를 @capgo/capacitor-file에서 확인하세요. 자연스러운 기능을 사용하는 데 @capgo/capacitor-file을 사용하세요. for the native capability in Using @capgo/capacitor-file.