Adresář dokumentů v mobilní aplikaci — co to je, účel a jak organizovat ukládání

Co je adresář dokumentů aplikace?

Adresář dokumentů — specializované úložiště v sandboxu aplikace určené pro trvalé ukládání uživatelských souborů. Na rozdíl od mezipaměti jsou soubory v tomto adresáři považovány za důležité pro uživatele: nejsou systémem mazány při nedostatku místa, jsou zachovány při aktualizaci aplikace a jsou zálohovány při synchronizaci zařízení. Na iOS je adresář Documents součástí Sandbox kontejneru a je automaticky zahrnut do zálohy iCloud. Na Androidu neexistuje přímý ekvivalent — ekvivalentem je context.filesDir, který je také určen pro trvalé soubory, ale nemá vestavěný mechanismus zálohování.

Rozdíl mezi adresářem dokumentů a interním úložištěm (Internal Storage) na Androidu je minimální: oba jsou v sandboxu aplikace, oba jsou smazány při odinstalaci, oba jsou nepřístupné jiným aplikacím. Hlavní rozdíl je sémantický: Documents Directory předpokládá, že soubory byly vytvořeny nebo importovány uživatelem, zatímco Internal Storage může obsahovat interní soubory aplikace (databáze, konfigurace). Na iOS je rozdíl významnější: Documents je automaticky zálohován, zatímco Library/Application Support nikoli. To ovlivňuje strategii ukládání: do Documents umisťujte pouze to, co chce uživatel obnovit na novém zařízení, a do Application Support — interní data, která může aplikace znovu vytvořit.

Architektura sandboxu zaručuje, že jiné aplikace nemají přístup k adresáři dokumentů vaší aplikace. Na iOS je přístup k Documents jiných aplikací nemožný bez jailbreaku. Na Androidu root přístup umožňuje číst filesDir libovolné aplikace, proto důvěrná data (tokeny, šifrovací klíče) musí být dodatečně chráněna pomocí EncryptedSharedPreferences nebo EncryptedFile z knihovny AndroidX Security.

Jaká data se ukládají v adresáři dokumentů

V adresáři dokumentů by měla být umístěna data, která mají pro uživatele hodnotu a měla by být dostupná po restartu aplikace nebo obnovení zařízení. Ne všechny soubory jsou vhodné pro ukládání v tomto adresáři — výběr závisí na typu dat a scénáři použití.

Uživatelské dokumenty a soubory

Uživatelské soubory — hlavní obsah adresáře dokumentů. Mohou to být textové dokumenty vytvořené v editoru, obrázky pořízené kamerou aplikace, exportované PDF zprávy, audio nahrávky, poznámky. Každý takový soubor byl vytvořen uživatelem nebo na jeho žádost a měl by být kdykoli k dispozici. Na iOS jsou soubory z Documents zobrazeny v systémové aplikaci Files, což umožňuje uživateli spravovat je pomocí standardního správce souborů. Na Androidu neexistuje podobné zobrazení — aplikace musí sama poskytnout rozhraní pro prohlížení uložených souborů.

Databáze a nastavení aplikace

SQLite databáze a konfigurační soubory jsou obvykle ukládány vedle adresáře dokumentů, ale ne v něm samotném. Na iOS jsou databáze umístěny v Library/Application Support, protože by se neměly zobrazovat v aplikaci Files a samostatně zálohovat. Na Androidu jsou databáze standardně vytvářeny v /data/data/<package>/databases/ pomocí Room nebo SQLiteOpenHelper. Pokud databáze obsahuje uživatelský obsah (poznámky, deník, finanční záznamy), lze ji umístit do filesDir pro zajištění zálohování prostřednictvím systému. Room umožňuje určit vlastní adresář pro ukládání databáze pomocí callbacku RoomDatabase.Builder.

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

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

Exportovaná a importovaná data

Soubory, které uživatel importuje z jiných aplikací nebo exportuje z vaší aplikace, by měly být také uloženy v adresáři dokumentů. Na iOS import prostřednictvím UIDocumentPickerViewController automaticky umístí kopii souboru do Documents při použití parametru asCopy: true. Na Androidu import prostřednictvím dialogu SAF také vytvoří kopii souboru v sandboxu aplikace. Při exportu dat (například vytvoření CSV souboru s kontakty) nejprve uložte soubor do Documents/filesDir a poté nabídněte uživateli sdílení prostřednictvím Share Sheet. To zaručuje, že i když uživatel zapomene soubor uložit po odeslání, kopie zůstane v aplikaci pro pozdější použití.

Jak pracovat s adresářem dokumentů na Androidu

Na Androidu funkce adresáře dokumentů plní context.filesDir. Dále je k dispozici adresář context.externalFilesDir na SD kartě, ale nezaručuje zachování dat. Pojďme prozkoumat hlavní techniky práce s těmito adresáři.

Přístup a správa souborů přes filesDir

filesDir — hlavní adresář pro trvalé soubory aplikace na Androidu. Nachází se v sandboxu aplikace a je zcela smazán při odinstalaci. Pro získání instance File použijte context.filesDir, který vrací cestu k adresáři /data/data/<package>/files/. Pro vytváření a čtení souborů použijte standardní File operace v Javě/Kotlinu nebo metody Context openFileInput() a openFileOutput(), které přijímají název souboru a vracejí FileInputStream/FileOutputStream. Metoda openFileOutput() automaticky vytvoří soubor ve filesDir, pokud ještě neexistuje, a umožňuje určit režim přístupu: MODE_PRIVATE (pouze aktuální aplikace), MODE_APPEND (připisování) nebo MODE_WORLD_READABLE (zastaralé, nepoužívá se od 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()
}

Vlastnosti ukládání na Android 10+

Na Android 10+ model Scoped Storage neovlivňuje filesDir — přístup k vlastnímu sandboxu aplikace zůstává plný. Všechny operace čtení a zápisu v filesDir nevyžadují další oprávnění. Při pokusu o přístup k souborům jiné aplikace přes filesDir však obdržíte výjimku. Pro výměnu souborů použijte FileProvider, který vytváří dočasný content URI pro přenos souboru do jiné aplikace. FileProvider se deklaruje v AndroidManifest.xml pomocí tagu <provider> a konfiguruje se v XML souboru cest. Toto je standardní mechanismus pro přenos souborů mezi aplikacemi, používaný například při odesílání obrázku přes Intent s ACTION_SEND.

Jak pracovat s adresářem dokumentů na iOS

Na iOS je Documents Directory součástí Sandbox kontejneru aplikace se zvláštním statusem. Soubory z tohoto adresáře jsou automaticky zahrnuty do zálohy iCloud, zobrazeny v aplikaci Files a zachovány při aktualizaci aplikace přes App Store.

Documents Directory a zálohování

Automatické zálohování Documents — klíčová výhoda iOS. Když uživatel připojí zařízení k iTunes nebo zapne iCloud Backup, všechny soubory z Documents/ jsou zkopírovány do zálohy. Při obnově na novém zařízení uživatel obdrží všechny své soubory bez dalších akcí. Tato výhoda se však stává nevýhodou, pokud aplikace ukládá velké objemy dat v Documents: doba zálohování se prodlužuje a úložiště iCloud může rychle dojít. Proto by v Documents měly být ukládány pouze soubory, které uživatel skutečně potřebuje při obnově. Dočasné soubory, mezipaměť a znovu vytvořitelná data by měla být v Caches nebo Library/Application Support. Apple doporučuje vyloučit ze zálohování soubory, které lze znovu stáhnout z internetu, pomocí atributu isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Obsah poznámky"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive a synchronizace mezi zařízeními

iCloud Drive umožňuje synchronizaci souborů z Documents mezi zařízeními stejného uživatele. Pro aktivaci synchronizace by aplikace měla používat API NSDocument nebo UIDocument, která automaticky spravují verzování a řešení konfliktů. Alternativní přístup — použití iCloud s CloudKit, který poskytuje flexibilnější kontrolu nad synchronizací, ale vyžaduje konfiguraci na CloudKit Dashboard. Při použití iCloud Drive se ujistěte, že správně zpracováváte editační konflikty (merge nebo last-write-wins) a informujete uživatele o stavu synchronizace prostřednictvím rozhraní aplikace. iCloud nezaručuje okamžitou synchronizaci — zpoždění může být od několika sekund do několika minut v závislosti na velikosti souboru a kvalitě připojení. Pro kriticky důležitá data používejte transakční zápis a verzování, aby bylo možné při konfliktu obnovit předchozí verzi souboru.

Rozdíly od Cache Directory a nejlepší postupy

Správná volba mezi Documents Directory a Cache Directory určuje spolehlivost ukládání uživatelských dat. Chyba ve volbě vede buď ke ztrátě dat (pokud jsou důležité soubory uloženy v mezipaměti), nebo k přeplnění zálohy (pokud jsou dočasné soubory uloženy v Documents).

Nejlepší postupy použití adresáře dokumentů zahrnují několik klíčových pravidel. Za prvé, vždy žádejte potvrzení uživatele před smazáním souborů z tohoto adresáře. Na rozdíl od mezipaměti může smazání dokumentu vést k nenávratné ztrátě uživatelského obsahu. Za druhé, implementujte verzování souborů: při přepisování existujícího souboru zachovejte předchozí verzi s příponou _backup nebo použijte Snapshot mechanismy. Za třetí, poskytněte uživateli rozhraní pro prohlížení, přejmenování, mazání a export souborů z adresáře dokumentů. Na iOS jsou soubory z Documents automaticky zobrazeny v Files, na Androidu je třeba implementovat vlastního správce souborů nebo použít knihovny třetích stran.

Zvláštní pozornost věnujte migraci dat při aktualizaci aplikace. Pokud nová verze mění strukturu ukládání souborů (například přesouvá data z jednoho podadresáře do druhého nebo mění formát souborů), implementujte jednorázovou migraci při prvním spuštění po aktualizaci. Ukládejte číslo verze schématu dat v SharedPreferences a při neshodě spusťte migraci. Neodstraňujte staré soubory do dokončení migrace — v případě selhání by uživatel neměl ztratit data. Pokud migrace zahrnuje konverzi formátu (například přechod z JSON na SQLite), uchovejte původní soubory jako zálohu v samostatném adresáři s datem migrace. Uživatel by měl mít možnost vrátit změny prostřednictvím nastavení aplikace během prvních 30 dnů po aktualizaci, jak doporučuje Apple Human Interface Guidelines.