Per iniziare
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-zip`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/zip/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
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-pluginsPoi usa il seguente prompt:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-zip` 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-zipbunx cap syncImporta
Sezione intitolata “Import”import { CapacitorZip } from '@capgo/capacitor-zip';Avvio rapido
Sezione intitolata “Quick start”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();Esempio: scompattare un bundle di update
Sezione intitolata “Esempio: estrarre un bundle di aggiornamento”await CapacitorZip.unzip({ source: downloadedZipUri, destination: unpackDirUri,});Errori comuni
Sezione intitolata “Errori comuni”- Zip web:
zip()genera un errore su web, offloada la compressione al nativo o al server. - Password Android: le password AES sono attualmente solo per Android, testa gli archivi su dispositivo.
- Schemi URI: usa assoluti
file://paths nativi che code può leggere.
Panoramica API
Sezione intitolata “Panoramica API”Comprimi un file o una directory per creare un archivio ZIP.
Crea un archivio compresso da un file o una directory di origine. Se la sorgente è una cartella, l'archivio includerà l'intera struttura della directory.
Note specifiche per piattaforma:
- iOS: la protezione con password non è supportata. Se viene fornita una password, verrà ignorata e verrà registrato un avviso.
- Android: supporta la crittografia AES-256 quando viene fornita una password.
- Web: non supportato. Genera un errore se chiamato.
import { CapacitorZip } from '@capgo/capacitor-zip';
// Compress a directory without passwordawait CapacitorZip.zip({ source: '/path/to/my-folder', destination: '/path/to/output.zip'});Estrai un archivio ZIP in una directory di destinazione specificata.
Estrae tutti i file e le cartelle da un archivio ZIP preservando la struttura delle directory. Crea la directory di destinazione se non esiste.
Note specifiche per piattaforma:
- iOS: supporta archivi ZIP standard. Gli archivi protetti da password vengono estratti con la password fornita.
- Android: supporta archivi cifrati con AES e password. Include protezione contro la vulnerabilità zip slip.
- Web: scarica ogni file individualmente nella cartella download del browser. Non può creare una struttura di directory.
import { CapacitorZip } from '@capgo/capacitor-zip';
// Extract a standard ZIP archiveawait CapacitorZip.unzip({ source: '/path/to/archive.zip', destination: '/path/to/extract-folder'});Riferimento ai tipi
Sezione: “Type Reference”ZipOptions
Sezione intitolata “ZipOptions”Opzioni per la creazione di un archivio 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
Sezione intitolata “UnzipOptions”Opzioni per l'estrazione di un archivio 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;}Fonte di verità
Sezione intitolata “Fonte di verità”Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.
Continua da Getting Started
Sezione intitolata “Continua da Getting Started”Se stai usando Per iniziare per pianificare le operazioni della dashboard e di API, collegalo a Utilizzo di @capgo/capacitor-zip per la funzionalità nativa in Utilizzo di @capgo/capacitor-zip, Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione in Chiavi API, e Dispositivi per i dettagli di implementazione in Dispositivi.