Documents Directory: ce este, scopul și accesul la fișiere

Ce este Documents Directory în iOS?

Documents Directory — este un director întân sandbox-ul aplicației iOS, destinat stocării datelor utilizatorului care trebuie păstrate între rulări și accesibile utilizatorului. Fiecare aplicație primește propriul sandbox izolat, iar Documents este unul dintre directoarele cheie alături de Caches, tmp și Library.

iOS folosește un sandbox strict: aplicația nu are acces la sistemul de fișiere al altor aplicații și la directoarele sistemului fără permisiuni speciale. Documents Directory — singurul director al cărui conținut poate fi vizualizat de utilizator prin iTunes File Sharing (la activarea cheii corespunzătoare UIFileSharingEnabled în Info.plist).

Conform datelor Apple WWDC 2023, peste 85% din aplicațiile din App Store folosesc Documents Directory pentru a stoca cel puțin un tip de date ale utilizatorului — de la PDF-uri exportate la fișiere de joc salvate și imagini exportate.

Dezvoltatorul trebuie să înțeleagă: fișierele din Documents sunt incluse automat în backup-ul iCloud și iTunes. Dacă aplicația stochează în Documents volume mari de date care pot fi restaurate (de exemplu, cache de imagini sau fișiere temporare), aceasta va duce la o ocupare nejustificată a spațiului în stocarea iCloud a utilizatorului.

Cum să obții calea către Documents Directory

În Swift, calea către Documents Directory se obține prin FileManager. Apple recomandă utilizarea API-ului bazat pe URL în loc de string-based pentru o mai bună compatibilitate cu capacitățile moderne ale iOS.

import Foundation

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

// Creează fișier în Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C folosește NSSearchPathForDirectoriesInDomains — o abordare mai veche, dar încă suportată, care returnează o cale sub formă de șir în loc de URL.

@import Foundation;

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

Proiectele moderne în Swift ar trebui să folosească FileManager.urls, deoarece această metodă returnează un URL, nu un șir, ceea ce reduce riscul de erori de codificare a căilor și face codul mai sigur din punct de vedere al tipurilor.

Ce date să stochezi în Documents

Documents Directory este destinată datelor create de utilizator sau necesare utilizatorului în formă explicită. Apple evidențiază mai multe categorii care sunt potrivite pentru acest director.

Documente și fișiere ale utilizatorului

Fișierele pe care utilizatorul le creează sau le importă — documente text, PDF, imagini, rapoarte exportate, fișiere de backup. Aceste date au valoare directă pentru utilizator, iar pierderea lor ar fi critică.

Salvări de jocuri și stare a aplicației

Salvările de jocuri, fișierele de stare ale aplicației, proiectele exportate — tot ceea ce utilizatorul se așteaptă să restabilească după reinstallarea aplicației. Cu toate acestea, pentru datele critice se recomandă utilizarea suplimentară a iCloud Key-Value Storage sau Core Data cu sincronizare iCloud.

Criteriul cheie: dacă datele pot fi restaurate din rețeaua sau recreate — locul lor este în Caches, nu în Documents. Fiecare gigaoctet în Documents este un gigaoctet în backup-ul iCloud al utilizatorului.

Backup și sincronizare

iOS include automat conținutul Documents Directory în backup la conectarea dispozitivului la iTunes sau la sincronizarea cu iCloud. Acest comportament nu poate fi dezactivat la nivel de director — doar fișier cu fișier prin atributul NSURLIsExcludedFromBackupKey.

Începând cu iOS 5.0, Apple a început să respingă aplicațiile care stochează în Documents volume mari de date care pot fi restaurate. Recomandarea Apple: fișierele care pot fi descărcate din nou trebuie stocate în Caches Directory cu flag de excludere din backup.

import Foundation

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

// Exclude fișierul din backup-ul iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Sincronizarea iCloud funcționează prin NSUbiquitousContainer dacă aplicația folosește iCloud Documents. În acest caz, fișierele din Documents Directory sunt sincronizate automat între dispozitivele utilizatorului. Pentru aplicațiile fără iCloud, sincronizarea se limitează la backup.

Documents Directory vs Caches Directory

Diferența dintre Documents și Caches — una dintre cele mai frecvente confuzii între dezvoltatorii iOS începători. Diferența principală: sistemul poate șterge în orice moment fișierele din Caches pentru a elibera spațiu, dar nu atinge niciodată Documents fără știrea utilizatorului.

Conform Apple Developer Documentation (2024), utilizarea incorectă a Documents Directory — una dintre cauzele frecvente de respingere a aplicațiilor la review: dacă aplicația stochează în Documents mai mult de câțiva megaocteți de date care pot fi restaurate, Apple recomandă mutarea lor în Caches sau aplicarea NSURLIsExcludedFromBackupKey.

Regulă practică: dacă utilizatorul va fi întristat la pierderea fișierului — stochează în Documents. Dacă fișierul poate fi re-descărcat sau generat — stochează în Caches.

Cele mai bune practici de lucru cu Documents

Dezvoltatorii iOS experimentați au elaborat câteva reguli care ajută la evitarea problemelor cu Documents Directory în toate etapele ciclului de viață al aplicației — de la dezvoltare la publicare în App Store.

Monitorizarea dimensiunii directorului

Verifică regulat dimensiunea Documents Directory prin FileManager.enumerator(at:includingPropertiesForKeys:). Dacă dimensiunea depășește 100 MB pentru date care nu sunt ale utilizatorului — acesta este un motiv pentru a reconsidera arhitectura de stocare.

Excluderea fișierelor recuperabile din backup

Pentru toate fișierele care pot fi re-descărcate din rețeaua, setează isExcludedFromBackup = true. Aceasta reduce încărcarea asupra stocării iCloud a utilizatorului și scade riscul de respingere a aplicației de către App Review.

Migrarea la actualizare

La modificarea formatului de date în Documents, prevede migrarea: nu șterge fișierele vechi până nu te asiguri că cele noi au fost create corect. Folosește subdirectoare specifice versiunii.

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
)

Respectarea acestor practici reduce riscul de pierdere a datelor utilizatorului, micșorează dimensiunea backup-ului iCloud și facilitează trecerea review-ului în App Store.