العمل مع أرشيفات ZIP في TypeScript: مكتبة JSZip والأدوات المساعدة

العمل مع أرشيفات ZIP في TypeScript: مكتبة JSZip وأمثلة عملية

\n\n

في تطوير الويب الحديث، غالباً ما تنشأ الحاجة إلى ضغط عدة ملفات في أرشيف واحد لسهولة التحميل أو نقل البيانات. في بيئة TypeScript (و JavaScript)، الحل الأكثر شيوعاً للعمل مع أرشيفات ZIP هو مكتبة JSZip. تتيح لك إنشاء وقراءة وتعديل ملفات ZIP سواء في المتصفح أو في بيئة Node.js.

\n\n

في هذه المقالة، سنشرح بالتفصيل عملية التثبيت والإعداد والسيناريوهات الأساسية لاستخدام JSZip في مشاريع TypeScript. ستتعلم كيفية إنشاء أرشيفات من نصوص وبيانات ثنائية ومجلدات كاملة، بالإضافة إلى استخراج محتويات ملفات ZIP الموجودة.

\n\n

تثبيت وإعداد JSZip

\n\n

للبدء، قم بتثبيت المكتبة وأنواعها عبر npm أو yarn:

\n\n

npm install jszip\nnpm install --save-dev @types/jszip

\n\n

بعد التثبيت، قم باستيراد JSZip في ملف TypeScript الخاص بك:

\n\n

import JSZip from 'jszip';

\n\n

إذا كنت تستخدم نظام الوحدات (ES modules)، سيعمل الاستيراد كما هو موضح أعلاه. بالنسبة لـ CommonJS (require) قد يختلف الصياغة، ولكن في مشاريع TypeScript يُوصى باستيرادات ES.

\n\n

إنشاء أرشيف ZIP جديد

\n\n

السيناريو الأبسط هو إنشاء أرشيف وإضافة عدة ملفات نصية إليه. لننظر إلى مثال:

\n\n

const zip = new JSZip();\n\n// إضافة ملفات نصية\nzip.file("hello.txt", "Hello, World!");\nzip.file("readme.md", "# وثائق\\n\\nهذا مثال لملف Markdown.");\n\n// إضافة مجلد وملف بداخله\nconst folder = zip.folder("images");\nfolder.file("logo.png", "base64encodedstring...", {base64: true});\n\n// إنشاء ملف ZIP كـ Blob\nzip.generateAsync({type: "blob"}).then((content) => {\n    // إنشاء رابط للتحميل\n    const link = document.createElement("a");\n    link.href = URL.createObjectURL(content);\n    link.download = "my-archive.zip";\n    link.click();\n});

\n\n

في هذا المثال قمنا بـ:

\n

\n
• إنشاء نسخة من JSZip
\n
• إضافة ملفين نصيين باستخدام طريقة .file()
\n
• إنشاء مجلد فرعي images ووضع ملف ببيانات base64 داخله
\n
• إنشاء الأرشيف بتنسيق Blob وبدء التحميل
\n

\n\n

قراءة واستخراج أرشيف ZIP موجود

\n\n

تتيح JSZip ليس فقط إنشاء الأرشيفات، بل أيضاً قراءتها. لهذا الغرض يتم استخدام طريقة loadAsync():

\n\n

async function readZipFile(zipBlob: Blob): Promise<void> {\n    try {\n        const zip = await JSZip.loadAsync(zipBlob);\n        \n        // الحصول على قائمة جميع الملفات\n        const fileNames = Object.keys(zip.files);\n        console.log("الملفات في الأرشيف:", fileNames);\n\n        // استخراج محتوى ملف معين\n        const helloFile = zip.file("hello.txt");\n        if (helloFile) {\n            const content = await helloFile.async("string");\n            console.log("محتوى hello.txt:", content);\n        }\n\n        // التكرار عبر جميع الملفات\n        zip.forEach((relativePath, zipEntry) => {\n            console.log(`تم العثور على ملف: ${relativePath}, الحجم: ${zipEntry._data.uncompressedSize} بايت`);\n        });\n\n    } catch (error) {\n        console.error("خطأ في قراءة ZIP:", error);\n    }\n}

\n\n

لاحظ التحديد النوعي: JSZip.loadAsync() يُرجع وعداً (Promise) يتحول إلى كائن JSZip. طريقة .file() تُرجع JSZipObject | null، لذا قبل استدعاء .async() يجب التحقق من وجود الملف.

\n\n

العمل مع البيانات الثنائية والصور

\n\n

غالباً ما يكون مطلوباً ضغط الصور أو ملفات ثنائية أخرى في أرشيف. تدعم JSZip العمل مع ArrayBuffer و Blob و Uint8Array و base64:

\n\n

// إضافة ملف من ArrayBu