دليل المستندات في التطبيق المحمول — ما هو، الغرض منه وكيفية تنظيم التخزين

ما هو دليل مستندات التطبيق؟

دليل المستندات هو تخزين متخصص داخل بيئة التطبيق الرملية (sandbox)، مصمم للتخزين الدائم لملفات المستخدم. على عكس ذاكرة التخزين المؤقت، تُعتبر الملفات في هذا الدليل مهمة للمستخدم: لا يحذفها النظام عند نقص المساحة، بل تُحفظ أثناء تحديثات التطبيق وتُنسخ احتياطياً أثناء مزامنة الجهاز. في iOS، دليل Documents هو جزء من حاوية Sandbox ويتم تضمينه تلقائياً في النسخ الاحتياطي لـ iCloud. في Android، لا يوجد معادل مباشر — المعادل هو context.filesDir، وهو مخصص أيضاً للملفات الدائمة ولكن ليس لديه آلية نسخ احتياطي مدمجة.

الفرق بين دليل المستندات والتخزين الداخلي (Internal Storage) على Android ضئيل: كلاهما موجود في بيئة التطبيق الرملية، كلاهما يُحذف عند إلغاء التثبيت، كلاهما غير متاح للتطبيقات الأخرى. الفرق الرئيسي دلالي: دليل Documents يفترض أن الملفات تم إنشاؤها أو استيرادها من قبل المستخدم، بينما التخزين الداخلي قد يحتوي على ملفات داخلية للتطبيق (قواعد بيانات، إعدادات). في iOS، الفرق أكبر: Documents يُنسخ احتياطياً تلقائياً، بينما Library/Application Support لا. هذا يؤثر على استراتيجية التخزين: ضع فقط ما يريد المستخدم استعادته على جهاز جديد في Documents، والبيانات الداخلية التي يمكن للتطبيق إعادة إنشائها في Application Support.

هندسة البيئة الرملية تضمن أن التطبيقات الأخرى لا يمكنها الوصول إلى دليل مستندات تطبيقك. في iOS، الوصول إلى Documents للتطبيقات الأخرى مستحيل دون كسر الحماية (jailbreak). في Android، الوصول الجذر (root) يسمح بقراءة filesDir لأي تطبيق، لذلك يجب حماية البيانات الحساسة (الرموز، مفاتيح التشفير) بشكل إضافي باستخدام EncryptedSharedPreferences أو EncryptedFile من مكتبة AndroidX Security.

ما البيانات التي تخزَّن في دليل المستندات

يجب أن يخزن دليل المستندات البيانات ذات القيمة للمستخدم والتي يجب أن تكون متاحة بعد إعادة تشغيل التطبيق أو استعادة الجهاز. ليست كل الملفات مناسبة للتخزين في هذا الدليل — يعتمد الاختيار على نوع البيانات وسيناريو الاستخدام.

مستندات وملفات المستخدم

ملفات المستخدم هي المحتوى الرئيسي لـ دليل المستندات. يمكن أن تكون مستندات نصية تم إنشاؤها في محرر، صوراً التقطتها كاميرا التطبيق، تقارير PDF مصدرة، تسجيلات صوتية، ملاحظات. كل ملف من هذا القبيل تم إنشاؤه بواسطة المستخدم أو بناءً على طلبه ويجب أن يكون متاحاً في أي لحظة. في iOS، تظهر الملفات من Documents في تطبيق Files النظامي، مما يسمح للمستخدم بإدارتها من خلال مدير الملفات القياسي. في Android، لا يوجد عرض مماثل — يجب أن يوفر التطبيق بنفسه واجهة لعرض الملفات المحفوظة.

قواعد البيانات وإعدادات التطبيق

قواعد بيانات SQLite وملفات الإعدادات تُخزَّن عادةً بالقرب من دليل المستندات ولكن ليس داخله. في iOS، توضع قواعد البيانات في Library/Application Support، لأنها لا يجب أن تظهر في تطبيق Files وتُنسخ احتياطياً بشكل منفصل. في Android، يتم إنشاء قواعد البيانات افتراضياً في /data/data/<package>/databases/ عبر Room أو SQLiteOpenHelper. إذا كانت قاعدة البيانات تحتوي على محتوى مستخدم (ملاحظات، مذكرات، سجلات مالية)، فيمكن وضعها في filesDir لضمان النسخ الاحتياطي عبر النظام. يتيح Room تحديد دليل تخزين مخصص لقاعدة البيانات عبر callback RoomDatabase.Builder.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

البيانات المصدرة والمستوردة

الملفات التي يستوردها المستخدم من التطبيقات الأخرى أو يصدرها من تطبيقك يجب أيضاً حفظها في دليل المستندات. في iOS، الاستيراد عبر UIDocumentPickerViewController يضع تلقائياً نسخة من الملف في Documents عند استخدام المعامل asCopy: true. في Android، الاستيراد عبر حوار SAF ينشئ أيضاً نسخة من الملف في بيئة التطبيق الرملية. عند تصدير البيانات (مثل إنشاء ملف CSV بجهات الاتصال)، احفظ الملف أولاً في Documents/filesDir، ثم قدم للمستخدم خيار مشاركته عبر Share Sheet. هذا يضمن أنه حتى إذا نسي المستخدم حفظ الملف بعد الإرسال، تبقى نسخة في التطبيق للاستخدام لاحقاً.

كيفية العمل مع دليل المستندات على Android

على Android، وظيفة دليل المستندات يؤديها context.filesDir. بالإضافة إلى ذلك، يتوفر الدليل context.externalFilesDir على بطاقة SD، لكنه لا يضمن سلامة البيانات. دعنا نستعرض التقنيات الرئيسية للعمل مع هذه الأدلة.

الوصول إلى الملفات وإدارتها عبر filesDir

filesDir هو الدليل الرئيسي للملفات الدائمة للتطبيق على Android. يقع في بيئة التطبيق الرملية ويُحذف بالكامل عند إلغاء التثبيت. للحصول على مثيل File، استخدم context.filesDir، الذي يعيد المسار إلى /data/data/<package>/files/. لإنشاء وقراءة الملفات، استخدم عمليات Java/Kotlin File القياسية أو طرق Context openFileInput() و openFileOutput()، التي تأخذ اسم ملف وتعيد FileInputStream/FileOutputStream. الطريقة openFileOutput() تنشئ الملف تلقائياً في filesDir إذا لم يكن موجوداً بعد وتسمح بتحديد وضع الوصول: MODE_PRIVATE (التطبيق الحالي فقط)، MODE_APPEND (إلحاق)، أو MODE_WORLD_READABLE (مهمل، غير مستخدم منذ API 24+).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

ميزات التخزين على Android 10+

على Android 10+، نموذج Scoped Storage لا يؤثر على filesDir — يبقى الوصول الكامل إلى بيئة التطبيق الرملية الخاصة به. جميع عمليات القراءة والكتابة داخل filesDir لا تتطلب أذونات إضافية. ومع ذلك، عند محاولة الوصول إلى ملفات تطبيق آخر عبر filesDir، ستحصل على استثناء. لمشاركة الملفات، استخدم FileProvider، الذي ينشئ URI محتوى مؤقتاً لنقل ملف إلى تطبيق آخر. يتم تعريف FileProvider في AndroidManifest.xml عبر الوسم <provider> وتكوينه في ملف XML للمسارات. هذه هي الآلية القياسية لنقل الملفات بين التطبيقات، المستخدمة مثلاً عند إرسال صورة عبر Intent مع ACTION_SEND.

كيفية العمل مع دليل المستندات على iOS

على iOS، Documents Directory هو جزء من حاوية Sandbox للتطبيق بوضع خاص. يتم تضمين الملفات من هذا الدليل تلقائياً في النسخ الاحتياطي لـ iCloud، وتظهر في تطبيق Files، وتُحفظ أثناء تحديثات التطبيق عبر App Store.

دليل المستندات والنسخ الاحتياطي

النسخ الاحتياطي التلقائي لـ Documents هو ميزة رئيسية في iOS. عندما يوصّل المستخدم الجهاز إلى iTunes أو يفعل iCloud Backup، تُنسخ جميع الملفات من Documents/ إلى النسخة الاحتياطية. عند الاستعادة على جهاز جديد، يحصل المستخدم على جميع ملفاته دون إجراءات إضافية. ومع ذلك، تصبح هذه الميزة عيباً إذا خزّن التطبيق كميات كبيرة من البيانات في Documents: يزيد وقت النسخ الاحتياطي وقد ينفد تخزين iCloud بسرعة. لذلك، يجب أن يخزن Documents فقط الملفات التي يحتاجها المستخدم حقاً أثناء الاستعادة. الملفات المؤقتة، وذاكرة التخزين المؤقت، والبيانات القابلة لإعادة الإنشاء يجب أن تكون في Caches أو Library/Application Support. توصي Apple باستبعاد الملفات التي يمكن إعادة تنزيلها من الإنترنت من النسخ الاحتياطي، عبر السمة isExcludedFromBackup.

let fm = FileManager.default
let docsURL = fm.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "محتوى الملاحظة"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive والمزامنة بين الأجهزة

iCloud Drive يسمح بمزامنة الملفات من Documents عبر أجهزة المستخدم. لتفعيل المزامنة، يجب على التطبيق استخدام API NSDocument أو UIDocument، التي تدير تلقائياً التحكم بالإصدارات وحل النزاعات. نهج بديل هو استخدام iCloud مع CloudKit، الذي يوفر تحكماً أكثر مرونة في المزامنة ولكنه يتطلب تهيئة على CloudKit Dashboard. عند استخدام iCloud Drive، تأكد من معالجة نزاعات التحرير بشكل صحيح (دمج أو آخر كاتب يفوز) وإعلام المستخدم بحالة المزامنة عبر واجهة التطبيق. iCloud لا يضمن المزامنة الفورية — قد يتراوح التأخير من بضع ثوانٍ إلى عدة دقائق حسب حجم الملف وجودة الاتصال. للبيانات الحرجة، استخدم الكتابة المعاملاتية والتحكم بالإصدارات بحيث يمكن استعادة الإصدار السابق للملف في حالة النزاع.

الاختلافات عن دليل التخزين المؤقت وأفضل الممارسات

الاختيار الصحيح بين Documents Directory و Cache Directory يحدد موثوقية تخزين بيانات المستخدم. خطأ في الاختيار يؤدي إما إلى فقدان البيانات (إذا كانت الملفات المهمة مخزنة في ذاكرة التخزين المؤقت) أو إلى امتلاء النسخ الاحتياطي (إذا كانت الملفات المؤقتة مخزنة في Documents).

أفضل الممارسات لاستخدام دليل المستندات تتضمن عدة قواعد رئيسية. أولاً، اطلب دائماً تأكيد المستخدم قبل حذف الملفات من هذا الدليل. على عكس ذاكرة التخزين المؤقت، قد يؤدي حذف مستند إلى فقدان لا رجعة فيه لمحتوى المستخدم. ثانياً، نفذ التحكم بإصدارات الملفات: عند الكتابة فوق ملف موجود، احفظ الإصدار السابق باللاحقة _backup أو استخدم آليات Snapshot. ثالثاً، وفر للمستخدم واجهة لعرض وإعادة تسمية وحذف وتصدير الملفات من دليل المستندات. في iOS، تظهر الملفات من Documents تلقائياً في Files؛ في Android، تحتاج إلى تنفيذ مدير ملفات خاص بك أو استخدام مكتبات طرف ثالث.

انتبه بشكل خاص لـ ترحيل البيانات أثناء تحديثات التطبيق. إذا كان الإصدار الجديد يغير هيكل تخزين الملفات (على سبيل المثال، ينقل البيانات من دليل فرعي إلى آخر أو يغير تنسيق الملف)، نفذ ترحيلاً لمرة واحدة عند أول تشغيل بعد التحديث. خزّن رقم إصدار مخطط البيانات في SharedPreferences وقم بتشغيل الترحيل إذا لم يتطابقا. لا تحذف الملفات القديمة قبل اكتمال الترحيل — في حالة الفشل، يجب ألا يفقد المستخدم البيانات. إذا كان الترحيل يتضمن تحويل تنسيق (مثل الانتقال من JSON إلى SQLite)، احفظ الملفات الأصلية كنسخة احتياطية في دليل منفصل مع تاريخ الترحيل. يجب أن يكون المستخدم قادراً على التراجع عن التغييرات عبر إعدادات التطبيق خلال أول 30 يوماً بعد التحديث، كما توصي Apple Human Interface Guidelines.