multi_unzip 2.0.3+6

مكتبة لفك ضغط الملفات (ZIP / RAR / TAR / GZ) تعمل على Android و Windows

📦 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+6

ثم نفّذ:

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.

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

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/.