Documents Directory: vad är det, syfte och åtkomst till filer

Vad är Documents Directory i iOS?

Documents Directory — är en katalog inuti iOS-applikationens sandlåda, avsedd för lagring av användardata som måste bevaras mellan körningar och vara tillgängliga för användaren. Varje applikation får sin egen isolerade sandlåda, och Documents är en av nyckelkatalogerna tillsammans med Caches, tmp och Library.

iOS använder en strikt sandlåda: applikationen har inte åtkomst till andra applikationers filsystem och systemkataloger utan särskilda behörigheter. Documents Directory — den enda katalog vars innehåll användaren kan visa via iTunes File Sharing (när motsvarande nyckel UIFileSharingEnabled aktiveras i Info.plist).

Enligt data från Apple WWDC 2023 använder över 85% av applikationerna i App Store Documents Directory för att lagra åtminstone en typ av användardata — från exporterade PDF-filer till sparade spelfiler och exporterade bilder.

Utvecklaren måste förstå: filer i Documents inkluderas automatiskt i iCloud- och iTunes-säkerhetskopian. Om applikationen lagrar stora mängder återställningsbara data i Documents (till exempel bildcache eller temporära filer), kommer detta att leda till oberättigad förbrukning av utrymme i användarens iCloud-lagring.

Hur får man sökvägen till Documents Directory

I Swift erhålls sökvägen till Documents Directory via FileManager. Apple rekommenderar att använda URL-baserat API istället för strängbaserat för bättre kompatibilitet med moderna iOS-funktioner.

import Foundation

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

// Skapa fil i Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C använder NSSearchPathForDirectoriesInDomains — ett äldre men fortfarande understött tillvägagångssätt som returnerar en strängväg istället för en URL.

@import Foundation;

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

Moderna projekt i Swift bör använda FileManager.urls eftersom denna metod returnerar en URL, inte en sträng, vilket minskar risken för fel med sökvägskodning och gör koden mer typ säker.

Vilka data ska lagras i Documents

Documents Directory är avsedd för data som skapats av användaren eller som användaren behöver i explicit form. Apple framhäver flera kategorier som är lämpliga för denna katalog.

Användardokument och filer

Filer som användaren skapar eller importerar — textdokument, PDF-filer, bilder, exporterade rapporter, säkerhetskopior. Dessa data har direkt värde för användaren, och deras förlust skulle vara kritisk.

Sparade spel och applikationstillstånd

Sparade spel, applikationstillståndsfiler, exporterade projekt — allt som användaren förväntar sig att återställa efter ominstallation av applikationen. För kritisk data rekommenderas dock även att använda iCloud Key-Value Storage eller Core Data med iCloud-synkronisering.

Nyckelkriterium: om data kan återställas från nätverket eller återskapas — deras plats är i Caches, inte i Documents. Varje gigabyte i Documents är en gigabyte i användarens iCloud-säkerhetskopia.

Säkerhetskopiering och synkronisering

iOS inkluderar automatiskt innehållet i Documents Directory i säkerhetskopian när enheten ansluts till iTunes eller vid synkronisering med iCloud. Detta beteende kan inte inaktiveras på katalognivå — endast fil för fil via attributet NSURLIsExcludedFromBackupKey.

Från och med iOS 5.0 började Apple avvisa applikationer som lagrar stora mängder återställningsbara data i Documents. Apples rekommendation: filer som kan laddas ner igen bör lagras i Caches Directory med flagga för uteslutning från säkerhetskopian.

import Foundation

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

// Exkludera fil från iCloud-säkerhetskopia
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

iCloud-synkronisering fungerar via NSUbiquitousContainer om applikationen använder iCloud Documents. I så fall synkroniseras filer från Documents Directory automatiskt mellan användarens enheter. För applikationer utan iCloud är synkroniseringen begränsad till säkerhetskopiering.

Documents Directory vs Caches Directory

Skillnaden mellan Documents och Caches — en av de vanligaste missuppfattningarna bland börjande iOS-utvecklare. Huvudskillnaden: systemet kan när som helst ta bort filer från Caches för att frigöra utrymme, men rör aldrig Documents utan användarens vetskap.

Enligt Apple Developer Documentation (2024) är felaktig användning av Documents Directory — en av de vanliga orsakerna till avvisning av applikationer vid granskning: om applikationen lagrar mer än några megabyte återställningsbara data i Documents, rekommenderar Apple att flytta dem till Caches eller tillämpa NSURLIsExcludedFromBackupKey.

Praktisk regel: om användaren blir ledsen över förlusten av filen — lagra i Documents. Om filen kan laddas ner eller genereras igen — lagra i Caches.

Bästa praxis för arbete med Documents

Erfarna iOS-utvecklare har utarbetat flera regler som hjälper till att undvika problem med Documents Directory i alla faser av applikationens livscykel — från utveckling till publicering i App Store.

Övervakning av katalogstorlek

Kontrollera regelbundet storleken på Documents Directory via FileManager.enumerator(at:includingPropertiesForKeys:). Om storleken överstiger 100 MB för data som inte är användardata — är detta en anledning att ompröva lagringsarkitekturen.

Uteslutning av återställningsbara filer från säkerhetskopian

För alla filer som kan laddas ner igen från nätverket, ställ in isExcludedFromBackup = true. Detta minskar belastningen på användarens iCloud-lagring och minskar risken för avvisning av applikationen av App Review.

Migrering vid uppdatering

När dataformatet i Documents ändras, förutse migrering: ta inte bort gamla filer förrän du är säker på att nya har skapats korrekt. Använd versionsspecifika underkataloger.

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
)

Att följa dessa metoder minskar risken för förlust av användardata, minskar storleken på iCloud-säkerhetskopian och underlättar granskningsprocessen i App Store.