Trabalho com arquivos ZIP em TypeScript: biblioteca JSZip e utilitários

Trabalho com arquivos ZIP em TypeScript: biblioteca JSZip e exemplos práticos

No desenvolvimento web moderno, surge frequentemente a necessidade de empacotar vários arquivos em um único arquivo para facilitar o download ou a transferência de dados. No ecossistema TypeScript (e JavaScript), a solução mais popular para trabalhar com arquivos ZIP é a biblioteca JSZip. Ela permite criar, ler e modificar arquivos ZIP tanto no navegador quanto no ambiente Node.js.

Neste artigo, abordaremos detalhadamente a instalação, configuração e os principais cenários de uso do JSZip em projetos TypeScript. Você aprenderá a criar arquivos a partir de strings, dados binários e pastas inteiras, além de extrair o conteúdo de arquivos ZIP existentes.

Instalação e importação do JSZip

Para começar, instale a biblioteca e seus tipos via npm ou yarn:

npm install jszipnpm install --save-dev @types/jszip

Após a instalação, importe o JSZip no seu arquivo TypeScript:

import JSZip from 'jszip';

Se você estiver usando um sistema de módulos (ES modules), a importação funcionará como mostrado acima. Para CommonJS (require), a sintaxe pode ser diferente, mas em projetos TypeScript é recomendado usar importações ES.

Criação de um novo arquivo ZIP

O cenário mais simples é criar um arquivo e adicionar alguns arquivos de texto. Veja o exemplo:

const zip = new JSZip();

// Adicionando arquivos de textozip.file("hello.txt", "Olá, Mundo!");zip.file("readme.md", "# Documentação

Este é um exemplo de arquivo Markdown.");

// Adicionando uma pasta e um arquivo dentro delaconst folder = zip.folder("imagens");folder.file("logo.png", "stringcodificadaembase64...", {base64: true});

// Gerando o arquivo ZIP como Blobzip.generateAsync({type: "blob"}).then((content) => {    // Criando um link para download    const link = document.createElement("a");    link.href = URL.createObjectURL(content);    link.download = "meu-arquivo.zip";    link.click();});

Neste exemplo, nós:

• Criamos uma instância de JSZip
• Adicionamos dois arquivos de texto usando o método .file()
• Criamos uma pasta aninhada imagens e colocamos um arquivo com dados em base64 dentro dela
• Geramos o arquivo no formato Blob e iniciamos o download

Leitura e extração de um arquivo ZIP existente

O JSZip permite não apenas criar, mas também ler arquivos. Para isso, use o método loadAsync():

async function lerArquivoZip(zipBlob: Blob): Promise<void> {    try {        const zip = await JSZip.loadAsync(zipBlob);                // Obtendo a lista de todos os arquivos        const nomesArquivos = Object.keys(zip.files);        console.log("Arquivos no ZIP:", nomesArquivos);

        // Extraindo o conteúdo de um arquivo específico        const arquivoOla = zip.file("hello.txt");        if (arquivoOla) {            const conteudo = await arquivoOla.async("string");            console.log("Conteúdo de hello.txt:", conteudo);        }

        // Iterando sobre todos os arquivos        zip.forEach((relativePath, zipEntry) => {            console.log(`Arquivo encontrado: ${relativePath}, tamanho: ${zipEntry._data.uncompressedSize} bytes`);        });

    } catch (error) {        console.error("Erro ao ler o ZIP:", error);    }}

Observe a tipagem: JSZip.loadAsync() retorna uma promise que é resolvida em um objeto JSZip. O método .file() retorna JSZipObject | null, portanto, antes de chamar .async(), é necessário verificar a existência do arquivo.

Trabalho com dados binários e imagens

Frequentemente, é necessário empacotar imagens ou outros arquivos binários em um arquivo. O JSZip suporta trabalho com ArrayBuffer, Blob, Uint8Array e base64:

// Adicionando um arquivo a partir de ArrayBu