Dokumentkatalogen i mobilappen — vad är det, syfte och hur man organiserar lagring

Vad är appens dokumentkatalog?

Dokumentkatalogen — en specialiserad lagringsplats i appens sandlåda, avsedd för permanent lagring av användarfiler. Till skillnad från cache anses filerna i denna katalog vara viktiga för användaren: de tas inte bort av systemet vid platsbrist, bevaras vid appuppdateringar och säkerhetskopieras vid enhetssynkronisering. På iOS är Documents-katalogen en del av Sandbox-behållaren och inkluderas automatiskt i iCloud-säkerhetskopiering. På Android finns ingen direkt motsvarighet — context.filesDir tjänar som motsvarighet, även avsedd för permanenta filer, men utan inbyggd säkerhetskopieringsmekanism.

Skillnaden mellan dokumentkatalogen och intern lagring (Internal Storage) på Android är minimal: båda finns i appens sandlåda, båda tas bort vid avinstallation, båda är otillgängliga för andra appar. Huvudskillnaden är semantisk: Documents Directory förutsätter att filerna har skapats eller importerats av användaren, medan Internal Storage kan innehålla interna appfiler (databaser, konfigurationer). På iOS är skillnaden mer betydande: Documents säkerhetskopieras automatiskt, medan Library/Application Support inte gör det. Detta påverkar lagringsstrategin: i Documents placerar du bara det användaren vill återställa på en ny enhet, och i Application Support — interna data som appen kan återskapa.

Sandlådans arkitektur garanterar att andra appar inte har åtkomst till din apps dokumentkatalog. På iOS är åtkomst till andras appar Documents omöjlig utan jailbreak. På Android möjliggör root-åtkomst läsning av filesDir för vilken app som helst, därför måste konfidentiella data (tokens, krypteringsnycklar) skyddas ytterligare med EncryptedSharedPreferences eller EncryptedFile från AndroidX Security-biblioteket.

Vilka data lagras i dokumentkatalogen

I dokumentkatalogen bör data placeras som är värdefulla för användaren och måste vara tillgängliga efter omstart av appen eller återställning av enheten. Alla filer är inte lämpliga för lagring i denna katalog — valet beror på datatyp och användningsscenario.

Användardokument och filer

Användarfiler — huvudinnehållet i dokumentkatalogen. Dessa kan vara textdokument skapade i redigeraren, bilder tagna med appens kamera, exporterade PDF-rapporter, ljudinspelningar, anteckningar. Varje sådan fil har skapats av användaren eller på dennes begäran och måste vara tillgänglig när som helst. På iOS visas filer från Documents i systemappen Files, vilket gör att användaren kan hantera dem via standardfilhanteraren. På Android finns ingen liknande visning — appen måste själv tillhandahålla ett gränssnitt för att visa sparade filer.

Databaser och appinställningar

SQLite-databaser och inställningsfiler lagras vanligtvis bredvid dokumentkatalogen, men inte i den själv. På iOS placeras databaser i Library/Application Support, eftersom de inte ska visas i Files-appen och säkerhetskopieras separat. På Android skapas databaser som standard i /data/data/<package>/databases/ via Room eller SQLiteOpenHelper. Om databasen innehåller användarinnehåll (anteckningar, dagbok, finansiella poster) kan den placeras i filesDir för att säkerställa säkerhetskopiering via systemet. Room tillåter att ange en anpassad katalog för databaslagring via RoomDatabase.Builder-återanropet.

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

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

Exporterade och importerade data

Filer som användaren importerar från andra appar eller exporterar från din app, bör också sparas i dokumentkatalogen. På iOS placerar import via UIDocumentPickerViewController automatiskt en kopia av filen i Documents när parametern asCopy: true används. På Android skapar import via SAF-dialogrutan också en kopia av filen i appens sandlåda. Vid export av data (till exempel skapa en CSV-fil med kontakter), spara först filen i Documents/filesDir och erbjud sedan användaren att dela den via Share Sheet. Detta garanterar att även om användaren glömmer att spara filen efter sändning, finns en kopia kvar i appen för senare användning.

Hur man arbetar med dokumentkatalogen på Android

På Android utförs funktionerna för dokumentkatalogen av context.filesDir. Dessutom finns katalogen context.externalFilesDir på SD-kortet, men den garanterar inte databevarande. Låt oss undersöka de viktigaste arbetsmetoderna med dessa kataloger.

Åtkomst och hantering av filer via filesDir

filesDir — huvudkatalogen för permanenta appfiler på Android. Den finns i appens sandlåda och tas helt bort vid avinstallation. För att få en File-instans, använd context.filesDir, som returnerar sökvägen till katalogen /data/data/<package>/files/. För att skapa och läsa filer, använd standard File-operationer i Java/Kotlin eller Context-metoderna openFileInput() och openFileOutput(), som accepterar filnamnet och returnerar FileInputStream/FileOutputStream. Metoden openFileOutput() skapar automatiskt filen i filesDir om den inte redan finns och tillåter att ange åtkomstläge: MODE_PRIVATE (endast aktuell app), MODE_APPEND (tillägg) eller MODE_WORLD_READABLE (föråldrat, används inte från 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()
}

Lagringsegenskaper på Android 10+

På Android 10+ påverkar Scoped Storage-modellen inte filesDir — åtkomsten till appens egen sandlåda förblir fullständig. Alla läs- och skrivoperationer i filesDir kräver inga ytterligare behörigheter. Vid försök att komma åt en annan apps filer via filesDir kommer du dock att få ett undantag. För filutbyte, använd FileProvider, som skapar en temporär content URI för att överföra filen till en annan app. FileProvider deklareras i AndroidManifest.xml via taggen <provider> och konfigureras i XML-sökvägsfilen. Detta är standardmekanismen för filöverföring mellan appar, som används till exempel vid sändning av en bild via Intent med ACTION_SEND.

Hur man arbetar med dokumentkatalogen på iOS

På iOS är Documents Directory en del av appens Sandbox-behållare med särskild status. Filer från denna katalog inkluderas automatiskt i iCloud-säkerhetskopiering, visas i Files-appen och bevaras vid appuppdatering via App Store.

Documents Directory och säkerhetskopiering

Automatisk säkerhetskopiering av Documents — den viktigaste fördelen med iOS. När användaren ansluter enheten till iTunes eller aktiverar iCloud Backup, kopieras alla filer från Documents/ till säkerhetskopian. Vid återställning på en ny enhet får användaren alla sina filer utan ytterligare åtgärder. Denna fördel blir dock en nackdel om appen lagrar stora datamängder i Documents: säkerhetskopieringstiden ökar och iCloud-lagringen kan ta slut snabbt. Därför bör endast filer som användaren verkligen behöver vid återställning lagras i Documents. Tillfälliga filer, cache och återskapningsbara data bör finnas i Caches eller Library/Application Support. Apple rekommenderar att utesluta filer som kan laddas ner igen från internet från säkerhetskopiering via attributet isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Anteckningens innehåll"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive och synkronisering mellan enheter

iCloud Drive möjliggör synkronisering av filer från Documents mellan enheter för samma användare. För att aktivera synkronisering bör appen använda API:et NSDocument eller UIDocument, som automatiskt hanterar versionshantering och konfliktlösning. Ett alternativt tillvägagångssätt — användning av iCloud med CloudKit, som ger mer flexibel kontroll över synkronisering, men kräver konfiguration på CloudKit Dashboard. När du använder iCloud Drive, se till att du hanterar redigeringskonflikter korrekt (merge eller last-write-wins) och informerar användaren om synkroniseringsstatus via appens gränssnitt. iCloud garanterar inte omedelbar synkronisering — fördröjningen kan vara från några sekunder till några minuter beroende på filstorlek och anslutningskvalitet. För kritiskt viktiga data, använd transaktionsskrivning och versionshantering, så att vid konflikt kan den tidigare versionen av filen återställas.

Skillnader från Cache Directory och bästa praxis

Rätt val mellan Documents Directory och Cache Directory avgör tillförlitligheten för lagring av användardata. Ett fel i valet leder antingen till dataförlust (om viktiga filer lagras i cache) eller till överfylld säkerhetskopia (om tillfälliga filer lagras i Documents).

Bästa praxis för användning av dokumentkatalogen inkluderar flera viktiga regler. För det första, be alltid om bekräftelse från användaren innan du tar bort filer från denna katalog. Till skillnad från cache kan borttagning av ett dokument leda till oåterkallelig förlust av användarinnehåll. För det andra, implementera versionshantering av filer: vid överskrivning av en befintlig fil, behåll den tidigare versionen med suffixet _backup eller använd Snapshot-mekanismer. För det tredje, ge användaren ett gränssnitt för att visa, byta namn, ta bort och exportera filer från dokumentkatalogen. På iOS visas filer från Documents automatiskt i Files, på Android måste du implementera en egen filhanterare eller använda tredjepartsbibliotek.

Ägna särskild uppmärksamhet åt datamigrering vid uppdatering av appen. Om den nya versionen ändrar fillagringsstrukturen (till exempel flyttar data från en underkatalog till en annan eller ändrar filformatet), implementera en engångsmigrering vid första starten efter uppdateringen. Lagra versionsnumret för dataschemat i SharedPreferences och starta migreringen vid obalans. Ta inte bort gamla filer förrän migreringen är klar — vid ett fel bör användaren inte förlora data. Om migreringen inkluderar formatkonvertering (till exempel övergång från JSON till SQLite), behåll originalfilerna som säkerhetskopia i en separat katalog med migreringsdatum. Användaren bör kunna ångra ändringar via appens inställningar inom de första 30 dagarna efter uppdateringen, som rekommenderas av Apple Human Interface Guidelines.