Panduan Memulai
Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.
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.
Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsLalu gunakan prompt berikut:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-zip` plugin in my project.Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:
bun add @capgo/capacitor-zipbunx cap syncimport { CapacitorZip } from '@capgo/capacitor-zip';Mulai cepat
Bagian berjudul “Mulai cepat”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();Contoh: unpack update bundle
Bagian berjudul “Contoh: unpack update bundle”await CapacitorZip.unzip({ source: downloadedZipUri, destination: unpackDirUri,});Kesalahan umum
Bagian berjudul “Kesalahan umum”- Web zip:
zip()akan error di web, pindahkan kompresi ke native atau server. - Password Android: Password AES saat ini hanya untuk Android, uji arsip di perangkat.
- Skema URI: gunakan path
file://absolut agar code native bisa membacanya.
Ringkasan API
Bagian berjudul “Ikhtisar API”Kompres file atau direktori untuk membuat arsip ZIP.
Membuat arsip terkompresi dari file atau direktori sumber. Arsip akan menyertakan seluruh struktur direktori jika sumbernya adalah folder.
Catatan khusus platform:
- iOS: Proteksi kata sandi tidak didukung. Jika kata sandi diberikan, maka akan diabaikan dan peringatan akan dicatat di logs.
- Android: Mendukung enkripsi AES-256 jika kata sandi diberikan.
- Web: Tidak didukung. Akan memunculkan error jika dipanggil.
import { CapacitorZip } from '@capgo/capacitor-zip';
// Compress a directory without passwordawait CapacitorZip.zip({ source: '/path/to/my-folder', destination: '/path/to/output.zip'});Ekstrak arsip ZIP ke direktori tujuan yang ditentukan.
Mengekstrak semua file dan folder dari arsip ZIP dengan tetap menjaga struktur direktori. Membuat direktori tujuan jika belum ada.
Catatan khusus platform:
- iOS: Mendukung arsip ZIP standar. Arsip yang dilindungi password diekstrak dengan password yang diberikan.
- Android: Mendukung arsip terenkripsi AES dengan password. Termasuk perlindungan terhadap kerentanan zip slip.
- Web: Mengunduh setiap file satu per satu ke folder unduhan browser. Tidak dapat membuat struktur direktori.
import { CapacitorZip } from '@capgo/capacitor-zip';
// Extract a standard ZIP archiveawait CapacitorZip.unzip({ source: '/path/to/archive.zip', destination: '/path/to/extract-folder'});Referensi Tipe
Bagian berjudul “Referensi Tipe”ZipOptions
Bagian berjudul “ZipOptions”Opsi untuk membuat arsip 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
Bagian berjudul “UnzipOptions”Opsi untuk mengekstrak arsip 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;}Sumber Kebenaran
Bagian berjudul “Sumber Kebenaran”Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.
Lanjutkan dari Getting Started
Bagian berjudul “Lanjutkan dari Getting Started”Jika Anda menggunakan Panduan Memulai untuk merencanakan operasi dashboard dan API, hubungkan dengan Menggunakan @capgo/capacitor-zip untuk kapabilitas native di Using @capgo/capacitor-zip, Ringkasan API untuk detail implementasi di API Overview, Pendahuluan untuk detail implementasi di Introduction, Kunci API untuk detail implementasi di API Keys, dan Perangkat untuk detail implementasi di Devices.