Iniziare

1. Installa il pacchetto

   npm

   npm i @capgo/capacitor-zip

   pnpm

   pnpm add @capgo/capacitor-zip

   yarn

   yarn add @capgo/capacitor-zip

   bun

   bun add @capgo/capacitor-zip

2. Sincronizzazione con progetti nativi

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Utilizzo

Importa il plugin e comprimi o decomprimi i file:

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

// Zip a folder
const zipFolder = async () => {
  await CapacitorZip.zip({
    source: 'file:///path/to/folder',
    destination: 'file:///path/to/archive.zip'
  });
  console.log('Folder zipped successfully!');
};

// Unzip an archive
const unzipArchive = async () => {
  await CapacitorZip.unzip({
    source: 'file:///path/to/archive.zip',
    destination: 'file:///path/to/output/folder'
  });
  console.log('Archive extracted successfully!');
};

API Riferimento

zip(opzioni)

Crea un archivio ZIP da una cartella di origine.

interface ZipOptions {
  source: string;       // Path to folder to compress
  destination: string;  // Path for output ZIP file
}

await CapacitorZip.zip({
  source: 'file:///path/to/folder',
  destination: 'file:///path/to/archive.zip'
});

decomprimere(opzioni)

Estrae file da un archivio ZIP.

interface UnzipOptions {
  source: string;       // Path to ZIP file
  destination: string;  // Path to extract to
}

await CapacitorZip.unzip({
  source: 'file:///path/to/archive.zip',
  destination: 'file:///path/to/output/folder'
});

Esempio completo

import { CapacitorZip } from '@capgo/capacitor-zip';
import { Filesystem, Directory } from '@capacitor/filesystem';

export class ZipService {
  async createBackup() {
    try {
      const timestamp = Date.now();
      const sourceDir = `${Filesystem.Directory.Data}/userdata`;
      const destPath = `${Filesystem.Directory.Documents}/backup_${timestamp}.zip`;

      await CapacitorZip.zip({
        source: sourceDir,
        destination: destPath
      });

      console.log('Backup created:', destPath);
      return destPath;
    } catch (error) {
      console.error('Backup failed:', error);
      throw error;
    }
  }

  async restoreBackup(backupPath: string) {
    try {
      const destDir = `${Filesystem.Directory.Data}/userdata`;

      // Clear existing data
      await Filesystem.rmdir({
        path: 'userdata',
        directory: Directory.Data,
        recursive: true
      });

      // Extract backup
      await CapacitorZip.unzip({
        source: backupPath,
        destination: destDir
      });

      console.log('Backup restored successfully');
    } catch (error) {
      console.error('Restore failed:', error);
      throw error;
    }
  }

  async compressFiles(filePaths: string[], outputPath: string) {
    try {
      // Create temporary directory
      const tempDir = `${Filesystem.Directory.Cache}/temp_zip_${Date.now()}`;

      await Filesystem.mkdir({
        path: tempDir,
        directory: Directory.Cache,
        recursive: true
      });

      // Copy files to temp directory
      for (const filePath of filePaths) {
        const fileName = filePath.split('/').pop();
        await Filesystem.copy({
          from: filePath,
          to: `${tempDir}/${fileName}`
        });
      }

      // Zip the temp directory
      await CapacitorZip.zip({
        source: tempDir,
        destination: outputPath
      });

      // Clean up temp directory
      await Filesystem.rmdir({
        path: tempDir,
        directory: Directory.Cache,
        recursive: true
      });

      return outputPath;
    } catch (error) {
      console.error('Compression failed:', error);
      throw error;
    }
  }

  async extractSpecificFiles(zipPath: string, fileNames: string[]) {
    try {
      // Extract to temp location
      const tempDir = `${Filesystem.Directory.Cache}/temp_extract_${Date.now()}`;

      await CapacitorZip.unzip({
        source: zipPath,
        destination: tempDir
      });

      // Read only specific files
      const extractedFiles: { [key: string]: string } = {};

      for (const fileName of fileNames) {
        const content = await Filesystem.readFile({
          path: `${tempDir}/${fileName}`,
          directory: Directory.Cache
        });
        extractedFiles[fileName] = content.data;
      }

      // Clean up
      await Filesystem.rmdir({
        path: tempDir,
        directory: Directory.Cache,
        recursive: true
      });

      return extractedFiles;
    } catch (error) {
      console.error('Extraction failed:', error);
      throw error;
    }
  }
}

Utilizzo avanzato

Creazione di archivi con monitoraggio dei progressi

const zipWithProgress = async (source: string, destination: string) => {
  console.log('Starting compression...');

  try {
    await CapacitorZip.zip({ source, destination });
    console.log('Compression complete!');
  } catch (error) {
    console.error('Compression failed:', error);
    throw error;
  }
};

Operazioni di archiviazione batch

const batchZip = async (folders: string[]) => {
  const results = [];

  for (const folder of folders) {
    const folderName = folder.split('/').pop();
    const zipPath = `${folder}_${Date.now()}.zip`;

    try {
      await CapacitorZip.zip({
        source: folder,
        destination: zipPath
      });
      results.push({ folder, zipPath, success: true });
    } catch (error) {
      results.push({ folder, error, success: false });
    }
  }

  return results;
};

Creazione di archivi sicuri

const createSecureBackup = async (dataPath: string) => {
  // Zip the data
  const zipPath = `${Filesystem.Directory.Documents}/secure_backup.zip`;

  await CapacitorZip.zip({
    source: dataPath,
    destination: zipPath
  });

  // Optionally encrypt the zip file here using a crypto plugin

  return zipPath;
};

Convalida dell’archivio

const validateArchive = async (zipPath: string): Promise<boolean> => {
  try {
    const tempDir = `${Filesystem.Directory.Cache}/validate_${Date.now()}`;

    // Try to extract
    await CapacitorZip.unzip({
      source: zipPath,
      destination: tempDir
    });

    // Clean up
    await Filesystem.rmdir({
      path: tempDir,
      directory: Directory.Cache,
      recursive: true
    });

    return true;
  } catch (error) {
    console.error('Archive validation failed:', error);
    return false;
  }
};

Migliori pratiche

1. Convalida del percorso: convalida sempre i percorsi di origine e di destinazione prima delle operazioni
2. Gestione degli errori: racchiude tutte le operazioni di zip/unzip in blocchi try-catch
3. Pulizia: rimuove file e cartelle temporanei dopo le operazioni
4. File di grandi dimensioni: fai attenzione con gli archivi di grandi dimensioni sui dispositivi mobili
5. Autorizzazioni: assicurati che la tua app disponga delle autorizzazioni necessarie per il file system

Risoluzione dei problemi

Problemi comuni

Operazione zip non riuscita: assicurati che il percorso di origine esista e sia accessibile Decompressione non riuscita: verifica che il file ZIP sia valido e che il percorso di destinazione sia scrivibile Archiviazione esaurita: monitora lo spazio su disco disponibile prima delle operazioni Autorizzazione negata: verifica le autorizzazioni del file system nella configurazione dell’app