A mobilalkalmazás dokumentumkönyvtára — mi ez, célja és hogyan szervezzük a tárolást

Mi az alkalmazás dokumentumkönyvtára?

A dokumentumkönyvtár — egy speciális tárolóhely az alkalmazás homokozójában, amely a felhasználói fájlok állandó tárolására szolgál. A gyorsítótárral ellentétben az ebben a könyvtárban lévő fájlok fontosnak minősülnek a felhasználó számára: a rendszer nem törli őket helyhiány esetén, megmaradnak az alkalmazás frissítésekor, és biztonsági mentés készül róluk az eszköz szinkronizálásakor. iOS-en a Documents könyvtár a Sandbox konténer része, és automatikusan bekerül az iCloud biztonsági mentésbe. Androidon nincs közvetlen megfelelője — a context.filesDir szolgál megfelelőként, amely szintén állandó fájlokra szolgál, de nincs beépített biztonsági mentési mechanizmusa.

A dokumentumkönyvtár és a belső tároló (Internal Storage) közötti különbség Androidon minimális: mindkettő az alkalmazás homokozójában található, mindkettő törlődik eltávolításkor, mindkettő elérhetetlen más alkalmazások számára. A fő különbség szemantikai: a Documents Directory feltételezi, hogy a fájlokat a felhasználó hozta létre vagy importálta, míg a Internal Storage tartalmazhat belső alkalmazásfájlokat (adatbázisok, konfigurációk). iOS-en a különbség jelentősebb: a Documents automatikusan biztonsági mentésre kerül, míg a Library/Application Support nem. Ez befolyásolja a tárolási stratégiát: a Documents-be csak azt helyezze, amit a felhasználó szeretne visszaállítani egy új eszközön, az Application Support-ba pedig azokat a belső adatokat, amelyeket az alkalmazás újrateremthet.

A homokozó architektúrája garantálja, hogy más alkalmazások nem férhetnek hozzá az Ön alkalmazásának dokumentumkönyvtárához. iOS-en más alkalmazások Documents-éhez való hozzáférés jailbreak nélkül lehetetlen. Androidon a root hozzáférés lehetővé teszi bármely alkalmazás filesDir-jének olvasását, ezért a bizalmas adatokat (tokenek, titkosítási kulcsok) tovább kell védeni az AndroidX Security könyvtár EncryptedSharedPreferences vagy EncryptedFile segítségével.

Milyen adatokat tárolnak a dokumentumkönyvtárban

A dokumentumkönyvtárban olyan adatokat kell elhelyezni, amelyek értéket képviselnek a felhasználó számára, és az alkalmazás újraindítása vagy az eszköz visszaállítása után is elérhetőnek kell lenniük. Nem minden fájl alkalmas tárolásra ebben a könyvtárban — a választás az adattípustól és a használati forgatókönyvtől függ.

Felhasználói dokumentumok és fájlok

A felhasználói fájlok — a dokumentumkönyvtár fő tartalma. Ezek lehetnek szöveges dokumentumok, amelyek a szerkesztőben készültek, az alkalmazás kamerájával készült képek, exportált PDF-jelentések, hangfelvételek, jegyzetek. Minden ilyen fájlt a felhasználó vagy az ő kérésére hoztak létre, és bármikor elérhetőnek kell lennie. iOS-en a Documents-ben lévő fájlok megjelennek a rendszer Files alkalmazásában, lehetővé téve a felhasználó számára, hogy a szabványos fájlkezelőn keresztül kezelje őket. Androidon nincs hasonló megjelenítés — az alkalmazásnak magának kell felületet biztosítania a mentett fájlok megtekintéséhez.

Adatbázisok és alkalmazásbeállítások

Az SQLite adatbázisokat és a beállításfájlokat általában a dokumentumkönyvtár mellett tárolják, de nem magában a könyvtárban. iOS-en az adatbázisokat a Library/Application Support mappába helyezik, mert nem szabad megjelenniük a Files alkalmazásban és külön biztonsági mentést készíteni róluk. Androidon az adatbázisok alapértelmezés szerint a /data/data/<package>/databases/ mappában jönnek létre Room vagy SQLiteOpenHelper segítségével. Ha az adatbázis felhasználói tartalmat tartalmaz (jegyzetek, napló, pénzügyi rekordok), elhelyezhető a filesDir-ben a rendszeren keresztüli biztonsági mentés biztosítása érdekében. A Room lehetővé teszi egyéni könyvtár megadását az adatbázis tárolásához a RoomDatabase.Builder callback-en keresztül.

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

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

Exportált és importált adatok

Azokat a fájlokat, amelyeket a felhasználó más alkalmazásokból importál vagy exportál az Ön alkalmazásából, szintén a dokumentumkönyvtárban kell tárolni. iOS-en az UIDocumentPickerViewController-en keresztüli importálás automatikusan elhelyezi a fájl másolatát a Documents-ben az asCopy: true paraméter használatakor. Androidon az SAF párbeszédpanelen keresztüli importálás szintén létrehozza a fájl másolatát az alkalmazás homokozójában. Adatok exportálásakor (például CSV-fájl létrehozása névjegyekkel) először mentse a fájlt a Documents/filesDir mappába, majd ajánlja fel a felhasználónak, hogy ossza meg a Share Sheeten keresztül. Ez garantálja, hogy még ha a felhasználó el is felejti elmenteni a fájlt a küldés után, a másolat az alkalmazásban marad későbbi használatra.

Hogyan dolgozzunk a dokumentumkönyvtárral Androidon

Androidon a dokumentumkönyvtár funkcióit a context.filesDir látja el. Emellett elérhető a context.externalFilesDir könyvtár az SD-kártyán, de ez nem garantálja az adatok megőrzését. Tekintsük át a főbb munkamódszereket ezekkel a könyvtárakkal.

Fájlok elérése és kezelése a filesDir segítségével

filesDir — az alkalmazás állandó fájljainak fő könyvtára Androidon. Az alkalmazás homokozójában található, és eltávolításkor teljesen törlődik. A File példányának lekéréséhez használja a context.filesDir-t, amely a /data/data/<package>/files/ könyvtár elérési útját adja vissza. Fájlok létrehozásához és olvasásához használja a szabványos File műveleteket Java/Kotlinben vagy a Context openFileInput() és openFileOutput() metódusait, amelyek elfogadják a fájlnevet és FileInputStream/FileOutputStream-t adnak vissza. Az openFileOutput() metódus automatikusan létrehozza a fájlt a filesDir-ben, ha még nem létezik, és lehetővé teszi a hozzáférési mód megadását: MODE_PRIVATE (csak az aktuális alkalmazás), MODE_APPEND (hozzáfűzés) vagy MODE_WORLD_READABLE (elavult, API 24+ óta nem használatos).

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()
}

Tárolási jellemzők Android 10+ rendszeren

Android 10+ rendszeren a Scoped Storage modell nem érinti a filesDir-t — a hozzáférés az alkalmazás saját homokozójához továbbra is teljes marad. A filesDir-en belüli összes olvasási és írási művelet nem igényel további engedélyeket. Azonban más alkalmazás fájljainak filesDir-en keresztüli elérésére tett kísérletkor kivételt kap. Fájlcseréhez használja a FileProvider-t, amely ideiglenes content URI-t hoz létre a fájl másik alkalmazásnak történő továbbításához. A FileProvider-t az AndroidManifest.xml-ben kell deklarálni a <provider> tagon keresztül, és egy XML elérési út fájlban kell konfigurálni. Ez a szabványos mechanizmus a fájlok alkalmazások közötti átvitelére, amelyet például kép küldésekor használnak Intent segítségével ACTION_SEND paraméterrel.

Hogyan dolgozzunk a dokumentumkönyvtárral iOS-en

iOS-en a Documents Directory az alkalmazás Sandbox konténerének része, különleges státusszal. Az ebből a könyvtárból származó fájlok automatikusan bekerülnek az iCloud biztonsági mentésbe, megjelennek a Files alkalmazásban, és megmaradnak az alkalmazás App Store-on keresztüli frissítésekor.

Documents Directory és biztonsági mentés

A Documents automatikus biztonsági mentése — az iOS kulcsfontosságú előnye. Amikor a felhasználó csatlakoztatja az eszközt az iTunes-hoz vagy bekapcsolja az iCloud Backup-ot, a Documents/ mappában lévő összes fájl átmásolásra kerül a biztonsági másolatba. Új eszközön történő visszaállításkor a felhasználó minden fájlját megkapja további műveletek nélkül. Ez az előny azonban hátránnyá válik, ha az alkalmazás nagy mennyiségű adatot tárol a Documents-ben: a biztonsági mentés ideje megnő, és az iCloud tárhely gyorsan kimerülhet. Ezért a Documents-ben csak azokat a fájlokat szabad tárolni, amelyekre a felhasználónak ténylegesen szüksége van a visszaállításkor. Az ideiglenes fájlokat, a gyorsítótárat és az újrateremthető adatokat a Caches vagy Library/Application Support mappában kell tárolni. Az Apple azt javasolja, hogy az internetről újratölthető fájlokat zárják ki a biztonsági mentésből az isExcludedFromBackup attribútum segítségével.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "A jegyzet tartalma"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive és szinkronizálás eszközök között

Az iCloud Drive lehetővé teszi a Documents-ből származó fájlok szinkronizálását ugyanazon felhasználó eszközei között. A szinkronizálás engedélyezéséhez az alkalmazásnak a NSDocument vagy UIDocument API-t kell használnia, amelyek automatikusan kezelik a verziókezelést és a konfliktusok feloldását. Alternatív megközelítés — az iCloud használata a CloudKit-tel, amely rugalmasabb vezérlést biztosít a szinkronizálás felett, de konfigurációt igényel a CloudKit Dashboard-on. Az iCloud Drive használatakor győződjön meg arról, hogy megfelelően kezeli a szerkesztési konfliktusokat (merge vagy last-write-wins), és tájékoztatja a felhasználót a szinkronizálás állapotáról az alkalmazás felületén keresztül. Az iCloud nem garantálja az azonnali szinkronizálást — a késleltetés néhány másodperctől néhány percig terjedhet a fájl méretétől és a kapcsolat minőségétől függően. Kritikus fontosságú adatok esetén használjon tranzakciós írást és verziókezelést, hogy konfliktus esetén vissza lehessen állítani a fájl előző verzióját.

Különbségek a Cache Directory-tól és legjobb gyakorlatok

A helyes választás a Documents Directory és a Cache Directory között meghatározza a felhasználói adatok tárolásának megbízhatóságát. A választás hibája vagy adatvesztéshez vezet (ha a fontos fájlok a gyorsítótárban vannak tárolva), vagy a biztonsági mentés túlcsordulásához (ha az ideiglenes fájlok a Documents-ben vannak tárolva).

Legjobb gyakorlatok a dokumentumkönyvtár használatához számos kulcsszabályt foglal magában. Először is, mindig kérje a felhasználó megerősítését, mielőtt fájlokat töröl ebből a könyvtárból. A gyorsítótárral ellentétben egy dokumentum törlése a felhasználói tartalom visszafordíthatatlan elvesztéséhez vezethet. Másodszor, valósítsa meg a fájlok verziókezelését: egy meglévő fájl felülírásakor tartsa meg az előző verziót a _backup utótaggal, vagy használjon Snapshot mechanizmusokat. Harmadszor, biztosítson a felhasználónak felületet a dokumentumkönyvtárból származó fájlok megtekintéséhez, átnevezéséhez, törléséhez és exportálásához. iOS-en a Documents-ben lévő fájlok automatikusan megjelennek a Files-ben, Androidon saját fájlkezelőt kell implementálni vagy harmadik féltől származó könyvtárakat kell használni.

Különös figyelmet fordítson az adat migrációra az alkalmazás frissítésekor. Ha az új verzió megváltoztatja a fájlok tárolási szerkezetét (például az adatokat egyik alkönyvtárból a másikba helyezi át, vagy megváltoztatja a fájlformátumot), valósítson meg egyszeri migrációt a frissítés utáni első indításkor. Tárolja az adatséma verziószámát a SharedPreferences-ben, és eltérés esetén indítsa el a migrációt. Ne törölje a régi fájlokat a migráció befejezéséig — hiba esetén a felhasználó nem veszítheti el az adatokat. Ha a migráció formátumkonverziót is tartalmaz (például átállás JSON-ról SQLite-re), őrizze meg az eredeti fájlokat biztonsági másolatként egy külön könyvtárban a migráció dátumával. A felhasználónak képesnek kell lennie a változtatások visszavonására az alkalmazás beállításain keresztül a frissítés utáni első 30 napban, ahogy azt az Apple Human Interface Guidelines ajánlja.