Documents Directory: ما هو، الغرض منه والوصول إلى الملفات

ما هو Documents Directory في iOS؟

Documents Directory هو دليل داخل بيئة الحماية (sandbox) لتطبيق iOS مصمم لتخزين بيانات المستخدم التي يجب أن تستمر بين جلسات التشغيل وتكون متاحة للمستخدم. يحصل كل تطبيق على sandbox معزول خاص به، و Documents هو أحد الأدلة الرئيسية إلى جانب Caches و tmp و Library.

يستخدم iOS sandbox صارماً: لا يمكن للتطبيق الوصول إلى نظام الملفات للتطبيقات الأخرى أو إلى أدلة النظام دون أذونات خاصة. Documents Directory هو الدليل الوحيد الذي يمكن للمستخدم عرض محتوياته عبر iTunes File Sharing (عند تمكين مفتاح UIFileSharingEnabled في Info.plist).

وفقاً لـ Apple WWDC 2023، أكثر من 85% من التطبيقات في App Store تستخدم Documents Directory لتخزين نوع واحد على الأقل من بيانات المستخدم — من ملفات PDF المصدرة إلى ملفات الألعاب المحفوظة والصور المصدرة.

من المهم أن يفهم المطور: الملفات في Documents يتم تضمينها تلقائياً في النسخ الاحتياطية لـ iCloud و iTunes. إذا كان التطبيق يخزن كميات كبيرة من البيانات القابلة للاستعادة في Documents (مثل ذاكرة تخزين الصور المؤقتة أو الملفات المؤقتة)، فإن ذلك يؤدي إلى استهلاك غير ضروري لمساحة تخزين iCloud الخاصة بالمستخدم.

كيفية الحصول على المسار إلى Documents Directory

في Swift، يتم الحصول على المسار إلى Documents Directory عبر FileManager. توصي Apple باستخدام API القائم على URL بدلاً من النصوص للحصول على توافق أفضل مع إمكانيات iOS الحديثة.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// إنشاء ملف في Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

يستخدم Objective-C NSSearchPathForDirectoriesInDomains — وهو نهج أقدم ولكن لا يزال مدعوماً، ويعيد مساراً نصياً بدلاً من URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

يجب أن تستخدم المشاريع الحديثة في Swift FileManager.urls، لأن هذه الطريقة تعيد URL بدلاً من نص، مما يقلل من خطر أخطاء ترميز المسارات ويجعل الكود أكثر أماناً من حيث الأنواع.

ما البيانات التي يجب تخزينها في Documents

Documents Directory مخصص للبيانات التي أنشأها المستخدم أو التي يحتاجها المستخدم بشكل صريح. تسلط Apple الضوء على عدة فئات مناسبة لهذا الدليل.

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

الملفات التي يقوم المستخدم بإنشائها أو استيرادها — مستندات نصية، PDF، صور، تقارير مصدرة، ملفات نسخ احتياطي. هذه البيانات لها قيمة مباشرة للمستخدم، وفقدانها سيكون أمراً بالغ الأهمية.

حفظ الألعاب وحالة التطبيق

حفظ الألعاب، ملفات حالة التطبيق، المشاريع المصدرة — كل ما يتوقع المستخدم استعادته بعد إعادة تثبيت التطبيق. ومع ذلك، للبيانات الحرجة يُوصى باستخدام iCloud Key-Value Storage أو Core Data مع مزامنة iCloud.

المعيار الرئيسي: إذا كان يمكن إعادة تنزيل البيانات من الشبكة أو إعادة إنشائها — فهي تنتمي إلى Caches، وليس Documents. كل غيغابايت في Documents هو غيغابايت في نسخة iCloud الاحتياطية للمستخدم.

النسخ الاحتياطي والمزامنة

iOS يتضمن تلقائياً محتويات Documents Directory في النسخ الاحتياطية عند توصيل الجهاز بـ iTunes أو عند المزامنة مع iCloud. لا يمكن تعطيل هذا السلوك على مستوى الدليل — فقط لكل ملف عبر الخاصية NSURLIsExcludedFromBackupKey.

بدءاً من iOS 5.0، بدأت Apple في رفض التطبيقات التي تخزن كميات كبيرة من البيانات القابلة للاستعادة في Documents. توصية Apple: الملفات التي يمكن إعادة تنزيلها يجب تخزينها في Caches Directory مع علامة استثناء النسخ الاحتياطي.

import Foundation

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

// استبعاد الملف من النسخة الاحتياطية لـ iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

تعمل مزامنة iCloud عبر NSUbiquitousContainer إذا كان التطبيق يستخدم iCloud Documents. في هذه الحالة، يتم مزامنة الملفات من Documents Directory تلقائياً بين أجهزة المستخدم. للتطبيقات بدون iCloud، تقتصر المزامنة على النسخ الاحتياطي.

Documents Directory مقابل Caches Directory

الفرق بين Documents و Caches هو واحد من أكثر المفاهيم الخاطئة شيوعاً بين مطوري iOS المبتدئين. الفرق الرئيسي: يمكن للنظام حذف الملفات من Caches في أي وقت لتحرير المساحة، لكنه لا يلمس Documents أبداً دون علم المستخدم.

وفقاً لـ Apple Developer Documentation (2024)، الاستخدام غير الصحيح لـ Documents Directory هو أحد الأسباب الشائعة لرفض التطبيقات أثناء المراجعة: إذا كان التطبيق يخزن أكثر من بضعة ميغابايت من البيانات القابلة للاستعادة في Documents، توصي Apple بنقلها إلى Caches أو تطبيق NSURLIsExcludedFromBackupKey.

قاعدة عملية: إذا كان المستخدم سينزعج من فقدان الملف — خزنه في Documents. إذا كان الملف يمكن إعادة تنزيله أو إعادة إنشائه — خزنه في Caches.

أفضل الممارسات للعمل مع Documents

طور مطورو iOS ذوو الخبرة عدة قواعد تساعد في تجنب المشكلات مع Documents Directory في جميع مراحل دورة حياة التطبيق — من التطوير إلى النشر في App Store.

مراقبة حجم الدليل

بانتظام تحقق من حجم Documents Directory عبر FileManager.enumerator(at:includingPropertiesForKeys:). إذا تجاوز الحجم 100 ميغابايت لبيانات غير مستخدم — فهذا سبب لإعادة النظر في بنية التخزين.

استثناء الملفات القابلة للاستعادة من النسخ الاحتياطي

لأي ملفات يمكن إعادة تنزيلها من الشبكة، قم بتعيين isExcludedFromBackup = true. هذا يقلل من الحمل على تخزين iCloud الخاص بالمستخدم ويقلل من خطر رفض التطبيق في App Review.

الترحيل أثناء التحديثات

عند تغيير تنسيق البيانات في Documents، خطط للترحيل: لا تحذف الملفات القديمة حتى تتأكد من إنشاء الملفات الجديدة بشكل صحيح. استخدم أدلة فرعية خاصة بالإصدار.

import Foundation

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

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

اتباع هذه الممارسات يقلل من خطر فقدان بيانات المستخدم، ويقلل من حجم النسخة الاحتياطية لـ iCloud، ويبسط مراجعة App Store.