Directorul de documente în aplicația mobilă — ce este, scopul și cum să organizezi stocarea

Ce este directorul de documente al aplicației?

Directorul de documente — un spațiu de stocare specializat în sandbox-ul aplicației, destinat păstrării permanente a fișierelor utilizatorului. Spre deosebire de cache, fișierele din acest director sunt considerate importante pentru utilizator: nu sunt șterse de sistem la lipsa de spațiu, se păstrează la actualizarea aplicației și sunt incluse în copia de rezervă la sincronizarea dispozitivului. Pe iOS, directorul Documents face parte din containerul Sandbox și este inclus automat în copia de rezervă iCloud. Pe Android nu există un echivalent direct — context.filesDir servește ca echivalent, destinat fișierelor permanente, dar fără mecanism încorporat de copiere de rezervă.

Diferența dintre directorul de documente și stocarea internă (Internal Storage) pe Android este minimă: ambele se află în sandbox-ul aplicației, ambele sunt șterse la dezinstalare, ambele sunt inaccesibile altor aplicații. Diferența principală este semantică: Documents Directory presupune că fișierele au fost create sau importate de utilizator, în timp ce Internal Storage poate conține fișiere interne ale aplicației (baze de date, configurații). Pe iOS diferența este mai semnificativă: Documents este copiat automat în rezervă, iar Library/Application Support — nu. Aceasta influențează strategia de stocare: în Documents plasați doar ceea ce utilizatorul dorește să restaureze pe un dispozitiv nou, iar în Application Support — datele interne pe care aplicația le poate recrea.

Arhitectura sandbox-ului garantează că alte aplicații nu au acces la directorul de documente al aplicației dumneavoastră. Pe iOS, accesul la Documents al altor aplicații este imposibil fără jailbreak. Pe Android, accesul root permite citirea filesDir al oricărei aplicații, de aceea datele confidențiale (token-uri, chei de criptare) trebuie protejate suplimentar cu EncryptedSharedPreferences sau EncryptedFile din biblioteca AndroidX Security.

Ce date se stochează în directorul de documente

În directorul de documente trebuie plasate datele care au valoare pentru utilizator și trebuie să fie disponibile după repornirea aplicației sau restaurarea dispozitivului. Nu toate fișierele sunt potrivite pentru stocarea în acest director — alegerea depinde de tipul datelor și scenariul de utilizare.

Documente și fișiere ale utilizatorului

Fișierele utilizatorului — conținutul principal al directorului de documente. Acestea pot fi documente text create în editor, imagini făcute cu camera aplicației, rapoarte PDF exportate, înregistrări audio, notițe. Fiecare astfel de fișier a fost creat de utilizator sau la cererea acestuia și trebuie să fie disponibil în orice moment. Pe iOS, fișierele din Documents sunt afișate în aplicația de sistem Files, permițând utilizatorului să le gestioneze prin managerul de fișiere standard. Pe Android nu există o afișare similară — aplicația trebuie să ofere propria interfață pentru vizualizarea fișierelor salvate.

Baze de date și setări ale aplicației

Bazele de date SQLite și fișierele de setări sunt de obicei stocate lângă directorul de documente, dar nu în el însuși. Pe iOS, bazele de date se plasează în Library/Application Support, deoarece nu trebuie să fie afișate în aplicația Files și copiate separat în rezervă. Pe Android, bazele de date sunt create implicit în /data/data/<package>/databases/ prin Room sau SQLiteOpenHelper. Dacă baza de date conține conținut al utilizatorului (notițe, jurnal, înregistrări financiare), poate fi plasată în filesDir pentru a asigura copierea de rezervă prin sistem. Room permite specificarea unui director personalizat pentru stocarea bazei de date prin callback-ul RoomDatabase.Builder.

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

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

Date exportate și importate

Fișierele pe care utilizatorul le importă din alte aplicații sau le exportă din aplicația dumneavoastră, trebuie de asemenea salvate în directorul de documente. Pe iOS, importul prin UIDocumentPickerViewController plasează automat o copie a fișierului în Documents când se folosește parametrul asCopy: true. Pe Android, importul prin dialogul SAF creează de asemenea o copie a fișierului în sandbox-ul aplicației. La exportul datelor (de exemplu, crearea unui fișier CSV cu contacte), salvați mai întâi fișierul în Documents/filesDir, apoi oferiți utilizatorului să îl partajeze prin Share Sheet. Aceasta garantează că, chiar dacă utilizatorul uită să salveze fișierul după trimitere, copia rămâne în aplicație pentru utilizare ulterioară.

Cum să lucrezi cu directorul de documente pe Android

Pe Android, funcțiile directorului de documente sunt îndeplinite de context.filesDir. Suplimentar, este disponibil directorul context.externalFilesDir pe cardul SD, dar acesta nu garantează păstrarea datelor. Să examinăm metodele principale de lucru cu aceste directoare.

Acces și gestionare a fișierelor prin filesDir

filesDir — directorul principal pentru fișierele permanente ale aplicației pe Android. Se află în sandbox-ul aplicației și este complet șters la dezinstalare. Pentru a obține o instanță File, utilizați context.filesDir, care returnează calea către directorul /data/data/<package>/files/. Pentru crearea și citirea fișierelor, utilizați operațiile standard File în Java/Kotlin sau metodele Context openFileInput() și openFileOutput(), care primesc numele fișierului și returnează FileInputStream/FileOutputStream. Metoda openFileOutput() creează automat fișierul în filesDir dacă nu există încă și permite specificarea modului de acces: MODE_PRIVATE (doar aplicația curentă), MODE_APPEND (adăugare) sau MODE_WORLD_READABLE (învechit, neutilizat de la 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()
}

Particularități de stocare pe Android 10+

Pe Android 10+, modelul Scoped Storage nu afectează filesDir — accesul la propriul sandbox al aplicației rămâne complet. Toate operațiile de citire și scriere în filesDir nu necesită permisiuni suplimentare. Cu toate acestea, la încercarea de a accesa fișierele altei aplicații prin filesDir veți primi o excepție. Pentru schimbul de fișiere, utilizați FileProvider, care creează un content URI temporar pentru transmiterea fișierului către o altă aplicație. FileProvider se declară în AndroidManifest.xml prin tag-ul <provider> și se configurează în fișierul XML de căi. Acesta este mecanismul standard pentru transferul fișierelor între aplicații, utilizat, de exemplu, la trimiterea unei imagini prin Intent cu ACTION_SEND.

Cum să lucrezi cu directorul de documente pe iOS

Pe iOS, Documents Directory face parte din containerul Sandbox al aplicației cu statut special. Fișierele din acest director sunt incluse automat în copia de rezervă iCloud, sunt afișate în aplicația Files și se păstrează la actualizarea aplicației prin App Store.

Documents Directory și copia de rezervă

Copierea automată de rezervă a Documents — avantajul cheie al iOS. Când utilizatorul conectează dispozitivul la iTunes sau activează iCloud Backup, toate fișierele din Documents/ sunt copiate în rezervă. La restaurarea pe un dispozitiv nou, utilizatorul primește toate fișierele fără acțiuni suplimentare. Cu toate acestea, acest avantaj devine un dezavantaj dacă aplicația stochează volume mari de date în Documents: timpul de copiere de rezervă crește, iar spațiul iCloud se poate epuiza rapid. De aceea, în Documents trebuie stocate doar fișierele cu adevărat necesare utilizatorului la restaurare. Fișierele temporare, cache-ul și datele care pot fi recreate trebuie să se afle în Caches sau Library/Application Support. Apple recomandă excluderea din copia de rezervă a fișierelor care pot fi re-descărcate de pe internet, prin atributul isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Conținutul notiței"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive și sincronizarea între dispozitive

iCloud Drive permite sincronizarea fișierelor din Documents între dispozitivele aceluiași utilizator. Pentru activarea sincronizării, aplicația trebuie să utilizeze API-ul NSDocument sau UIDocument, care gestionează automat versionarea și rezolvarea conflictelor. O abordare alternativă — utilizarea iCloud cu CloudKit, care oferă un control mai flexibil asupra sincronizării, dar necesită configurare pe CloudKit Dashboard. Când utilizați iCloud Drive, asigurați-vă că gestionați corect conflictele de editare (merge sau last-write-wins) și informați utilizatorul despre starea sincronizării prin interfața aplicației. iCloud nu garantează sincronizarea instantanee — întârzierea poate varia de la câteva secunde la câteva minute în funcție de dimensiunea fișierului și calitatea conexiunii. Pentru datele critice, utilizați scrierea tranzacțională și versionarea, astfel încât la un conflict să puteți restabili versiunea anterioară a fișierului.

Diferențe față de Cache Directory și cele mai bune practici

Alegerea corectă între Documents Directory și Cache Directory determină fiabilitatea stocării datelor utilizatorului. O eroare în alegere duce fie la pierderea datelor (dacă fișierele importante sunt stocate în cache), fie la supraîncărcarea copiei de rezervă (dacă fișierele temporare sunt stocate în Documents).

Cele mai bune practici de utilizare a directorului de documente includ câteva reguli cheie. În primul rând, solicitați întotdeauna confirmarea utilizatorului înainte de ștergerea fișierelor din acest director. Spre deosebire de cache, ștergerea unui document poate duce la pierderea ireversibilă a conținutului utilizatorului. În al doilea rând, implementați versionarea fișierelor: la suprascrierea unui fișier existent, păstrați versiunea anterioară cu sufixul _backup sau utilizați mecanisme Snapshot. În al treilea rând, oferiți utilizatorului o interfață pentru vizualizarea, redenumirea, ștergerea și exportul fișierelor din directorul de documente. Pe iOS, fișierele din Documents sunt afișate automat în Files, pe Android trebuie să implementați propriul manager de fișiere sau să utilizați biblioteci terțe.

Acordați o atenție deosebită migrării datelor la actualizarea aplicației. Dacă noua versiune modifică structura de stocare a fișierelor (de exemplu, mută datele dintr-un subdirector în altul sau schimbă formatul fișierelor), implementați o migrare unică la prima pornire după actualizare. Stocați numărul versiunii schemei de date în SharedPreferences și, la nepotrivire, lansați migrarea. Nu ștergeți fișierele vechi până la finalizarea migrării — în caz de defecțiune, utilizatorul nu trebuie să piardă date. Dacă migrarea include conversia formatului (de exemplu, trecerea de la JSON la SQLite), păstrați fișierele originale ca copie de rezervă într-un director separat cu data migrării. Utilizatorul trebuie să poată reveni la setările anterioare prin interfața aplicației în primele 30 de zile după actualizare, după cum recomandă Apple Human Interface Guidelines.