スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いの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-zip` plugin in my project.

手動セットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

bun add @capgo/capacitor-zip
bunx cap sync

インポート

import { CapacitorZip } from '@capgo/capacitor-zip';

クイックスタート

import { CapacitorZip } from '@capgo/capacitor-zip';

const listener = await CapacitorZip.addListener('progress', (event) => {
  updateBar(event.loaded, event.total);
});
await CapacitorZip.zip({
  source: 'file:///data/user/0/.../export/',
  destination: 'file:///data/user/0/.../export.zip',
});
await listener.remove();

例：アップデート用bundleの解凍

await CapacitorZip.unzip({
  source: downloadedZipUri,
  destination: unpackDirUri,
});

よくある落とし穴

• Web版 zip: zip() Webではエラーになります。圧縮処理はNativeまたはサーバーで行ってください。
• Androidのパスワード: AESパスワードは現在Androidのみ対応しています。アーカイブは実機でテストしてください。
• URIスキーム: 絶対パスを file:// 使用してください。Nativeの code が読み取れるパスである必要があります。

API の概要

zip

ファイルやディレクトリを圧縮してZIPアーカイブを作成します。

ソースファイルまたはディレクトリから圧縮アーカイブを作成します。ソースがフォルダの場合、ディレクトリ構造全体がアーカイブに含まれます。

プラットフォームごとの注意点:

• iOS: パスワード保護はサポートされていません。パスワードが指定された場合は無視され、警告がログに記録されます。
• Android: パスワード指定時、AES-256暗号化をサポートしています。
• Web: サポートされていません。呼び出すとエラーが発生します。

import { CapacitorZip } from '@capgo/capacitor-zip';

// Compress a directory without password
await CapacitorZip.zip({
  source: '/path/to/my-folder',
  destination: '/path/to/output.zip'
});

unzip

ZIPアーカイブを指定した出力先ディレクトリに展開します。

ディレクトリ構造を維持したまま、ZIPアーカイブ内のすべてのファイルとフォルダを展開します。出力先ディレクトリが存在しない場合は作成されます。

プラットフォームごとの注意点:

• iOS: 標準的なZIPアーカイブをサポートしています。パスワード保護されたアーカイブは、指定したパスワードで解凍可能です。
• Android: パスワード付きのAES暗号化アーカイブをサポートしています。zip slip脆弱性への対策も含まれています。
• Web: 各ファイルをブラウザのダウンロードフォルダに個別に保存します。ディレクトリ構造の作成はできません。

import { CapacitorZip } from '@capgo/capacitor-zip';

// Extract a standard ZIP archive
await CapacitorZip.unzip({
  source: '/path/to/archive.zip',
  destination: '/path/to/extract-folder'
});

型リファレンス

ZipOptions

ZIPアーカイブ作成時のオプション。

export interface ZipOptions {
  /**
   * Path to the file or directory to compress.
   *
   * This can be an absolute path or a path relative to the app's working directory.
   * If the source is a directory, all its contents will be recursively compressed
   * while preserving the directory structure.
   *
   * Platform-specific notes:
   * - iOS: Use file:// URLs or absolute paths. Relative paths are resolved from the app's documents directory.
   * - Android: Use absolute file paths or content:// URIs for files accessible via the Android Storage Access Framework.
   * - Web: Not supported.
   *
   * @since 7.0.0
   * @example '/Users/app/Documents/my-folder'
   * @example '/var/mobile/Containers/Data/Application/.../Documents/file.pdf'
   * @example 'file:///storage/emulated/0/Download/document.pdf'
   */
  source: string;

  /**
   * Path where the ZIP archive will be created.
   *
   * The destination path must include the .zip file extension. If the parent
   * directory doesn't exist, it will be created automatically.
   *
   * Platform-specific notes:
   * - iOS: Use file:// URLs or absolute paths. Relative paths are resolved from the app's documents directory.
   * - Android: Use absolute file paths. The plugin will create any missing parent directories.
   * - Web: Not supported.
   *
   * @since 7.0.0
   * @example '/Users/app/Documents/archive.zip'
   * @example '/var/mobile/Containers/Data/Application/.../Documents/backup.zip'
   * @example 'file:///storage/emulated/0/Download/compressed.zip'
   */
  destination: string;

  /**
   * Optional password for encrypting the ZIP archive.
   *
   * When provided, the archive will be encrypted and require this password
   * to extract. Uses AES-256 encryption on Android.
   *
   * Platform-specific notes:
   * - iOS: Password protection is NOT supported. The password will be ignored and a warning will be logged.
   * - Android: Supports AES-256 encryption via zip4j library. The password must be provided during extraction.
   * - Web: Not supported.
   *
   * @since 7.0.0
   * @example 'mySecurePassword123'
   */
  password?: string;

  /**
   * Whether to include the parent folder in the ZIP archive.
   *
   * When true (default), the source folder itself becomes the root directory in the archive.
   * When false, only the contents of the source folder are included at the root level.
   *
   * This option only applies when the source is a directory. For single files, this option is ignored.
   *
   * @default true
   * @since 8.0.5
   * @example
   * ```typescript
   * // With includeParentFolder: true (default)
   * // Source: /cache/temp/ containing [database.backup, media/]
   * // ZIP contains: temp/database.backup, temp/media/
   * await CapacitorZip.zip({
   *   source: '/cache/temp',
   *   destination: '/cache/backup.zip',
   *   includeParentFolder: true
   * });
   * ```
   * @example
   * ```typescript
   * // With includeParentFolder: false
   * // Source: /cache/temp/ containing [database.backup, media/]
   * // ZIP contains: database.backup, media/
   * await CapacitorZip.zip({
   *   source: '/cache/temp',
   *   destination: '/cache/backup.zip',
   *   includeParentFolder: false
   * });
   * ```
   */
  includeParentFolder?: boolean;
}

UnzipOptions

ZIPアーカイブ解凍時のオプション。

export interface UnzipOptions {
  /**
   * Path to the ZIP archive to extract.
   *
   * The source must be a valid ZIP file. If the file doesn't exist or is
   * corrupted, the operation will fail with an error.
   *
   * Platform-specific notes:
   * - iOS: Use file:// URLs or absolute paths. Relative paths are resolved from the app's documents directory.
   * - Android: Use absolute file paths or content:// URIs for files accessible via the Android Storage Access Framework.
   * - Web: Use HTTP/HTTPS URLs. The file will be fetched and extracted in the browser.
   *
   * @since 7.0.0
   * @example '/Users/app/Documents/archive.zip'
   * @example '/var/mobile/Containers/Data/Application/.../Documents/backup.zip'
   * @example 'file:///storage/emulated/0/Download/compressed.zip'
   * @example 'https://example.com/files/archive.zip' (Web only)
   */
  source: string;

  /**
   * Path to the directory where files will be extracted.
   *
   * The destination directory will be created if it doesn't exist. All files
   * and folders from the archive will be extracted while preserving the
   * directory structure.
   *
   * Platform-specific notes:
   * - iOS: Use file:// URLs or absolute paths. Relative paths are resolved from the app's documents directory.
   * - Android: Use absolute file paths. Includes protection against zip slip vulnerabilities.
   * - Web: Not applicable. Files are downloaded individually to the browser's download folder.
   *
   * @since 7.0.0
   * @example '/Users/app/Documents/extracted'
   * @example '/var/mobile/Containers/Data/Application/.../Documents/files'
   * @example 'file:///storage/emulated/0/Download/extracted-files'
   */
  destination: string;

  /**
   * Optional password for decrypting password-protected archives.
   *
   * Required if the ZIP archive was encrypted with a password. If the password
   * is incorrect, extraction will fail with an error.
   *
   * Platform-specific notes:
   * - iOS: Supports password-protected ZIP archives.
   * - Android: Supports AES-encrypted archives created with zip4j or standard password-protected ZIPs.
   * - Web: Not supported. Password-protected archives cannot be extracted in the browser.
   *
   * @since 7.0.0
   * @example 'mySecurePassword123'
   */
  password?: string;
}

Source of Truth

このページはプラグインの src/definitions.tsから生成されています。upstream で公開 API が変更されたら、再度 sync を実行してください。

Getting Startedの続きを進める

使用している場合 スタートガイド ダッシュボードと API の運用を計画するには、これを次と連携させます @capgo/capacitor-zip の使い方 @capgo/capacitor-zip を使う際のネイティブ機能については、 API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー および「API Keys」の実装の詳細については、 デバイス 実装の詳細については Devices を参照してください。