Documents Directory: co to je, účel a přístup k souborům

Co je Documents Directory v iOS?

Documents Directory — je adresář uvnitř sandboxu aplikace iOS, určený pro ukládání uživatelských dat, která mají být zachována mezi spuštěními a přístupná uživateli. Každá aplikace získává vlastní izolovaný sandbox a Documents je jedním z klíčových adresářů vedle Caches, tmp a Library.

iOS používá přísný sandbox: aplikace nemá přístup k souborovému systému jiných aplikací a systémovým adresářům bez zvláštních oprávnění. Documents Directory — jediný adresář, jehož obsah může uživatel prohlížet prostřednictvím iTunes File Sharing (při zapnutí příslušného klíče UIFileSharingEnabled v Info.plist).

Podle údajů Apple WWDC 2023 používá více než 85% aplikací v App Store Documents Directory k ukládání alespoň jednoho typu uživatelských dat — od exportovaných PDF po uložené herní soubory a exportované obrázky.

Vývojář musí pochopit: soubory v Documents jsou automaticky zahrnuty do zálohy iCloud a iTunes. Pokud aplikace ukládá do Documents velké objemy dat, která lze obnovit (například mezipaměť obrázků nebo dočasné soubory), povede to k neodůvodněnému zabírání místa v úložišti iCloud uživatele.

Jak získat cestu k Documents Directory

Ve Swift se cesta k Documents Directory získává pomocí FileManager. Apple doporučuje používat API založené na URL místo API založeného na řetězci pro lepší kompatibilitu s moderními možnostmi iOS.

import Foundation

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

// Vytvořit soubor v Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C používá NSSearchPathForDirectoriesInDomains — starší, ale stále podporovaný přístup, který vrací řetězcovou cestu místo URL.

@import Foundation;

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

Moderní projekty ve Swift by měly používat FileManager.urls, protože tato metoda vrací URL, nikoli řetězec, což snižuje riziko chyb s kódováním cest a činí kód typově bezpečnějším.

Jaká data ukládat v Documents

Documents Directory je určena pro data vytvořená uživatelem nebo potřebná uživateli v explicitní podobě. Apple zdůrazňuje několik kategorií, které jsou pro tento adresář vhodné.

Uživatelské dokumenty a soubory

Soubory, které uživatel vytváří nebo importuje — textové dokumenty, PDF, obrázky, exportované zprávy, zálohovací soubory. Tato data mají pro uživatele přímou hodnotu a jejich ztráta by byla kritická.

Uložené hry a stav aplikace

Uložené hry, soubory stavu aplikace, exportované projekty — vše, co uživatel očekává obnovit po přeinstalování aplikace. Pro kritická data se však doporučuje také používat iCloud Key-Value Storage nebo Core Data se synchronizací iCloud.

Klíčové kritérium: pokud lze data obnovit ze sítě nebo znovu vytvořit — jejich místo je v Caches, nikoli v Documents. Každý gigabajt v Documents je gigabajt v záloze iCloud uživatele.

Zálohování a synchronizace

iOS automaticky zahrnuje obsah Documents Directory do zálohy při připojení zařízení k iTunes nebo při synchronizaci s iCloud. Toto chování nelze vypnout na úrovni adresáře — pouze po souborech pomocí atributu NSURLIsExcludedFromBackupKey.

Od iOS 5.0 začala Apple odmítat aplikace, které ukládají do Documents velké objemy obnovitelných dat. Doporučení Apple: soubory, které lze znovu stáhnout, by měly být uloženy v Caches Directory s příznakem vyloučení ze zálohy.

import Foundation

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

// Vyloučit soubor ze zálohy iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Synchronizace iCloud funguje prostřednictvím NSUbiquitousContainer, pokud aplikace používá iCloud Documents. V tomto případě jsou soubory z Documents Directory automaticky synchronizovány mezi zařízeními uživatele. Pro aplikace bez iCloud je synchronizace omezena na zálohování.

Documents Directory vs Caches Directory

Rozdíl mezi Documents a Caches — jeden z nejčastějších omylů mezi začínajícími iOS vývojáři. Hlavní rozdíl: systém může kdykoli odstranit soubory z Caches pro uvolnění místa, ale nikdy nesahá do Documents bez vědomí uživatele.

Podle Apple Developer Documentation (2024) je nesprávné používání Documents Directory — jednou z častých příčin odmítnutí aplikací při recenzi: pokud aplikace ukládá do Documents více než několik megabajtů obnovitelných dat, Apple doporučuje je přesunout do Caches nebo použít NSURLIsExcludedFromBackupKey.

Praktické pravidlo: pokud bude uživatel smutný ze ztráty souboru — ukládej do Documents. Pokud lze soubor znovu stáhnout nebo vygenerovat — ukládej do Caches.

Nejlepší postupy práce s Documents

Zkušení iOS vývojáři vytvořili několik pravidel, která pomáhají vyhnout se problémům s Documents Directory ve všech fázích životního cyklu aplikace — od vývoje po publikování v App Store.

Sledování velikosti adresáře

Pravidelně kontroluj velikost Documents Directory pomocí FileManager.enumerator(at:includingPropertiesForKeys:). Pokud velikost přesahuje 100 MB pro data, která nejsou uživatelská — je to důvod k přehodnocení architektury úložiště.

Vyloučení obnovitelných souborů ze zálohy

Pro všechny soubory, které lze znovu stáhnout ze sítě, nastav isExcludedFromBackup = true. To sníží zatížení úložiště iCloud uživatele a sníží riziko odmítnutí aplikace App Review.

Migrace při aktualizaci

Při změně formátu dat v Documents počítej s migrací: neodstraňuj staré soubory, dokud si nejsi jistý, že nové byly správně vytvořeny. Používej podadresáře specifické pro verzi.

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
)

Dodržování těchto postupů snižuje riziko ztráty uživatelských dat, zmenšuje velikost zálohy iCloud a usnadňuje průchod recenzí v App Store.