📦 multi_unzip

مكتبة لفك ضغط الملفات لأنواع ZIP و RAR و TAR/GZ مع واجهة موحدة تعمل في Flutter.

  • Android: فك RAR عبر FFI وبناء مكتبة أصلية libunrar.so تلقائيًا (NDK/CMake).
  • Windows: فك RAR عبر أدوات النظام (مثل unrar.exe) أو بدائل موجودة، وZIP/TAR/GZ عبر Dart.
  • ZIP/TAR/GZ: عبر حزمة archive (Pure Dart) على جميع المنصات.

✨ المميزات

  • منصات Android، Windows (ودعم أنظمة إضافية لاحقًا).
  • صيغ zip، rar، tar، gz.
  • واجهة موحدة استدعاء واحد MultiUnzip.extract(...) يحدد النوع تلقائيًا.
  • ملفات كبيرة دعم الملفات الكبيرة مع تعريفات بناء مناسبة على أندرويد.
  • إعدادات بناء محسّنة تضمين رؤوس UnRAR عبر ${UNRAR_DIR} لضمان ترجمة صحيحة لملفات مثل coder.cpp.

📦 المتطلبات

  • على Android:
    • Android SDK + NDK + CMake مثبتة في بيئة التطوير لديك.
    • Gradle سيبني libunrar.so لواجهات ABI: armeabi-v7a، arm64-v8a (قابلة للتوسعة).
  • على Windows:
    • لفك RAR قد تحتاج وجود unrar.exe في المسار PATH (إن تعذّر المسار الافتراضي).

🔧 التثبيت

أضف إلى pubspec.yaml في تطبيقك:

dependencies:
  multi_unzip: ^2.0.3+9

ثم نفّذ:

flutter pub get

ملاحظة: الحزمة تعتمد على Flutter (Plugin مع FFI لأندرويد) وعلى ffi وarchive داخليًا.

🚀 الاستخدام السريع

import 'package:multi_unzip/multi_unzip.dart';

Future<void> demo() async {
  await MultiUnzip.extract(
    sourcePath: '/path/to/archive.rar',
    destinationDir: '/path/to/output',
  );
}

🚢 النشر على pub.dev (للمطورين)

  • تأكد من تحديث version في pubspec.yaml.

  • يوصى بإضافة أحد الحقلين لإزالة التحذير:

    • repository: https://github.com/<username>/multi_unzip
    • أو homepage: https://github.com/<username>/multi_unzip

  • أوامر سريعة:

    flutter pub get
flutter pub publish --dry-run
flutter pub publish

  • يحدد MultiUnzip النوع تلقائيًا من الامتداد (.zip/.rar/.tar/.gz).

  • على Android، يتم فك RAR عبر FFI لمكتبة أصلية مبنية تلقائيًا.

  • على منصات أخرى، يتم استخدام المسارات البديلة المجهزة (Pure Dart لـ ZIP/TAR/GZ، وبدائل RAR حيث أمكن).

🧩 تفاصيل المنصات

  • Android (RAR):

    • يتم تحميل libunrar.so واستدعاء دالة أصلية عبر dart:ffi.
    • يتطلب NDK/CMake في بيئة البناء. لا يلزم أي إعداد إضافي في مشروعك، فإعلان ffiPlugin: true يعتني بالبناء.

  • Windows (RAR):

    • محاولة استخدام أدوات النظام (مثل unrar.exe). تأكد من توفرها في PATH عند الضرورة.

  • جميع المنصات (ZIP/TAR/GZ):

    • باستخدام حزمة archive (Pure Dart)، لا يلزم تبعيات أصلية.

❗ ملاحظات

  • ملفات RAR المحمية بكلمة مرور غير مدعومة حاليًا في مسار FFI الافتراضي.
  • الالتزام بالرخصة الخاصة بـ UnRAR مطلوب عند توزيع تطبيقاتك. راجع native/unrar/unrar/license.txt.
  • تم ضبط مسار تضمين الرؤوس (headers) إلى جذر UnRAR عبر target_include_directories(unrar PRIVATE ${UNRAR_DIR}) لضمان ترجمة ملفات مثل coder.cpp بشكل صحيح.
  • تم استثناء ملف dll.cpp من البناء على أندرويد لتجنب مشاكل الربط الخاصة بـ RARDLL.
  • تم إضافة تضمين الرؤوس #include "rar.hpp" في unpack50.cpp, unpack50frag.cpp, unpack50mt.cpp ضمن هذا الإصدار.
  • تم نقل تعريفات unpackinline.cpp إلى unpack.hpp كـ inline، واستبعاد الملف من البناء.
  • تم تعطيل unpack50mt.cpp (وضع التعددية MT) في إعدادات CMake لأندرويد.

🧪 مثال أكثر تفصيلاً

import 'dart:io';
import 'package:multi_unzip/multi_unzip.dart';

Future<void> extractExample() async {
  final src = Platform.isAndroid
      ? '/sdcard/Download/sample.zip'
      : 'C:/Users/you/Downloads/sample.zip';
  final out = Platform.isAndroid
      ? '/sdcard/Download/output'
      : 'C:/Users/you/Downloads/output';

  await MultiUnzip.extract(sourcePath: src, destinationDir: out);
}

🐞 استكشاف الأخطاء الشائعة

  • تأكد من وجود مساحة كافية للكتابة في destinationDir.
  • على Android، إن واجهت خطأ في FFI:
    • تحقق من توافر NDK/CMake في بيئة Android SDK لديك.
    • حاول flutter clean && flutter pub get ثم أعد البناء.
  • على Windows، إن فشل فك RAR:
    • تحقق من توفر unrar.exe في PATH أو ثبّته من موقعه الرسمي.

📝 سجل التغييرات (Changelog)

  • 1.1.0:
    • إضافة دعم فك RAR على Android عبر FFI وبناء libunrar.so تلقائيًا.
    • الحفاظ على فك ZIP/TAR/GZ عبر archive (Pure Dart).
    • تحسين واجهة الاستخدام الموحدة MultiUnzip.extract.

📄 الرخصة

راجع ملف LICENSE. كود UnRAR يخضع لرخصته الخاصة والمشمولة مع المصادر ضمن native/unrar/unrar/.

Libraries

multi_unzip