Getting Started

Installieren

bun add @capgo/capacitor-zip
bunx cap sync

Importieren

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

API Übersicht

zip

Ein Datei oder Verzeichnis komprimieren, um ein ZIP-Archiv zu erstellen.

Erstellt ein komprimiertes Archiv aus einer Quelldatei oder einem Verzeichnis. Das Archiv wird die gesamte Verzeichnisstruktur enthalten, wenn die Quelle ein Verzeichnis ist.

Plattformspezifische Hinweise:

• iOS: Die Unterstützung von Passwörtern ist nicht möglich. Wenn ein Passwort angegeben wird, wird es ignoriert und eine Warnung wird protokolliert.
• Android: Unterstützt AES-256-Verschlüsselung, wenn ein Passwort angegeben wird.
• Web: Nicht unterstützt. Würft eine Fehlermeldung aus, wenn aufgerufen.

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

Ein ZIP-Archiv extrahieren Sie in einen angegebenen Zielordner.

Alle Dateien und Ordner aus einem ZIP-Archiv extrahiert, während die Verzeichnisstruktur beibehalten wird. Der Zielordner wird erstellt, wenn er nicht existiert.

Plattformspezifische Hinweise:

• iOS: Unterstützt Standard-ZIP-Archive. Passwortschützte Archive werden mit dem bereitgestellten Passwort extrahiert.
• Android: Unterstützt AES-verschlüsselte Archive mit Passwort. Enthält Schutz vor zip-Slip-Vulnerabilität.
• Website: Jede Datei einzeln herunterlädt und in den Download-Ordner des Browsers speichert. Eine Verzeichnisstruktur kann nicht erstellt werden.

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

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

Typenreferenz

ZipOptions

Optionen für die Erstellung eines ZIP-Archivs.

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

Einstellungen für die Extraktion eines ZIP-Archivs

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

Quelle der Wahrheit

Diese Seite wird aus dem Plugin generiert. src/definitions.tsWenn sich die öffentliche API im Quellcode ändert, führen Sie die Synchronisierung erneut durch.

Weiter von Getting Started

Wenn Sie "Getting Started" verwenden, um das Dashboard und die __CAPGO_KEEP_0__-Operationen zu planen, verbinden Sie es mit Getting Started um das Dashboard und die API-Operationen zu planen Mit @capgo/capacitor-zip verwenden für die native Fähigkeit in Mit @capgo/capacitor-zip verwenden API Übersicht für die Implementierungsdetails in API Übersicht Einführung für die Implementierungsdetails in Einführung API Schlüssel für die Implementierungsdetails in API Schlüssel, und Geräte für die Implementierungsdetails in Geräte.