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 را به جای string-based برای سازگاری بهتر با قابلیت‌های مدرن 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:) بررسی کن. اگر اندازه برای داده‌های غیرکاربری از ۱۰۰ مگابایت بیشتر شود — این دلیلی برای بازنگری معماری ذخیره‌سازی است.

حذف فایل‌های قابل بازیابی از پشتیبان

برای همه فایل‌هایی که می‌توان از شبکه دوباره دانلود کرد، 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 را آسان‌تر می‌کند.