Documents Directory: mi ez, célja és hozzáférés a fájlokhoz

Mi az a Documents Directory iOS-ben?

Documents Directory — egy könyvtár az iOS alkalmazás homokozójában, amely a felhasználói adatok tárolására szolgál, amelyeket az indítások között meg kell őrizni és a felhasználó számára elérhetővé kell tenni. Minden alkalmazás saját elkülönített homokozót kap, és a Documents az egyik kulcsfontosságú könyvtár a Caches, tmp és Library mellett.

Az iOS szigorú homokozót használ: az alkalmazásnak nincs hozzáférése más alkalmazások fájlrendszeréhez és rendszerkönyvtáraihoz különleges engedélyek nélkül. A Documents Directory — az egyetlen könyvtár, amelynek tartalmát a felhasználó megtekintheti az iTunes File Sharing segítségével (a megfelelő UIFileSharingEnabled kulcs bekapcsolásakor az Info.plist-ben).

Az Apple WWDC 2023 adatai szerint az App Store-ban lévő alkalmazások több mint 85%-a használja a Documents Directory-t legalább egyfajta felhasználói adat tárolására — az exportált PDF-ektől a mentett játékfájlokig és exportált képekig.

A fejlesztőnek meg kell értenie: a Documents-ben lévő fájlok automatikusan bekerülnek az iCloud és iTunes biztonsági mentésbe. Ha az alkalmazás nagy mennyiségű helyreállítható adatot tárol a Documents-ben (például képgyorsítótárat vagy ideiglenes fájlokat), ez a felhasználó iCloud tárhelyének indokolatlan elfoglalásához vezet.

Hogyan szerezzük meg az útvonalat a Documents Directory-hoz

Swift-ben a Documents Directory útvonalát a FileManager segítségével szerezheted meg. Az Apple az URL-alapú API használatát ajánloja a string-alapú helyett a modernebb iOS képességekkel való jobb kompatibilitás érdekében.

import Foundation

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

// Fájl létrehozása a Documents-ben
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Az Objective-C a NSSearchPathForDirectoriesInDomains használja — egy régebbi, de még mindig támogatott megközelítés, amely string útvonalat ad vissza URL helyett.

@import Foundation;

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

A Swift-ben lévő modern projekteknek a FileManager.urls-t kell használniuk, mert ez a metódus URL-t ad vissza, nem stringet, ami csökkenti az útvonal kódolásából származó hibák kockázatát és típusbiztonságosabbá teszi a kódot.

Milyen adatokat tároljunk a Documents-ben

Documents Directory a felhasználó által létrehozott vagy a felhasználó számára explicit formában szükséges adatok számára lett kialakítva. Az Apple több kategóriát emel ki, amelyek alkalmasak erre a könyvtárra.

Felhasználói dokumentumok és fájlok

Fájlok, amelyeket a felhasználó létrehoz vagy importál — szöveges dokumentumok, PDF-ek, képek, exportált jelentések, biztonsági mentési fájlok. Ezek az adatok közvetlen értékkel bírnak a felhasználó számára, és elvesztésük kritikus lenne.

Játékmentések és alkalmazás állapota

Játékmentések, alkalmazás állapotának fájljai, exportált projektek — minden, amit a felhasználó elvár helyreállítani az alkalmazás újratelepítése után. A kritikus adatokhoz azonban ajánlott az iCloud Key-Value Storage vagy az iCloud szinkronizálással rendelkező Core Data használata is.

A legfontosabb kritérium: ha az adatok visszaállíthatók a hálózatról vagy újra létrehozhatók — a helyük a Caches-ben van, nem a Documents-ben. Minden gigabájt a Documents-ben egy gigabájt a felhasználó iCloud biztonsági mentésében.

Biztonsági mentés és szinkronizálás

iOS automatikusan beleteszi a Documents Directory tartalmát a biztonsági mentésbe, amikor az eszközt csatlakoztatják az iTunes-hoz vagy amikor szinkronizálnak az iCloud-dal. Ez a viselkedés nem kapcsolható ki könyvtár szinten — csak fájlonként az NSURLIsExcludedFromBackupKey attribútum segítségével.

iOS 5.0-tól kezdve az Apple elutasítani kezdte azokat az alkalmazásokat, amelyek nagy mennyiségű helyreállítható adatot tárolnak a Documents-ben. Apple ajánlás: az újra letölthető fájlokat a Caches Directory-ban kell tárolni, a biztonsági mentésből való kizárási jelzővel.

import Foundation

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

// Fájl kizárása az iCloud biztonsági mentésből
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Az iCloud szinkronizálás az NSUbiquitousContainer-on keresztül működik, ha az alkalmazás iCloud Documents-t használ. Ebben az esetben a Documents Directory fájljai automatikusan szinkronizálódnak a felhasználó eszközei között. Az iCloud nélküli alkalmazásoknál a szinkronizálás a biztonsági mentésre korlátozódik.

Documents Directory vs Caches Directory

A Documents és a Caches közötti különbség — az egyik leggyakoribb tévhit a kezdő iOS fejlesztők körében. A fő különbség: a rendszer bármikor törölheti a Caches fájljait a hely felszabadítása érdekében, de soha nem nyúl a Documents-hoz a felhasználó tudta nélkül.

Az Apple Developer Documentation (2024) szerint a Documents Directory helytelen használata — az alkalmazások elutasításának gyakori oka a felülvizsgálat során: ha az alkalmazás több mint néhány megabájt helyreállítható adatot tárol a Documents-ben, az Apple ajánlja őket áthelyezni a Caches-be vagy alkalmazni az NSURLIsExcludedFromBackupKey-t.

Gyakorlati szabály: ha a felhasználó szomorú lesz a fájl elvesztésekor — tárold a Documents-ben. Ha a fájl újra letölthető vagy előállítható — tárold a Caches-ben.

Legjobb gyakorlatok a Documents használatához

A tapasztalt iOS fejlesztők számos szabályt dolgoztak ki, amelyek segítenek elkerülni a Documents Directory-val kapcsolatos problémákat az alkalmazás életciklusának minden szakaszában — a fejlesztéstől az App Store-beli kiadásig.

A könyvtár méretének figyelése

Rendszeresen ellenőrizd a Documents Directory méretét a FileManager.enumerator(at:includingPropertiesForKeys:) segítségével. Ha a méret meghaladja a 100 MB-ot olyan adatok esetén, amelyek nem felhasználói adatok — ez ok a tárolási architektúra újragondolására.

A helyreállítható fájlok kizárása a biztonsági mentésből

Minden olyan fájlhoz, amely újra letölthető a hálózatról, állítsd be az isExcludedFromBackup = true értéket. Ez csökkenti a felhasználó iCloud tárhelyének terhelését és csökkenti az alkalmazás App Review általi elutasításának kockázatát.

Migráció frissítéskor

Az adatformátum megváltoztatásakor a Documents-ben előre lásd el a migrációt: ne töröld a régi fájlokat, amíg nem győződtél meg arról, hogy az újak helyesen lettek létrehozva. Használj verzió-specifikus alkönyvtárakat.

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
)

E gyakorlatok betartása csökkenti a felhasználói adatok elvesztésének kockázatát, kisebbé teszi az iCloud biztonsági mentés méretét, és megkönnyíti az App Store felülvizsgálatának átjutását.