Storage Access Framework: vad det är, arbetsprinciper och åtkomst till filer

Vad är Storage Access Framework?

Storage Access Framework — är en del av Android SDK som ger ett enhetligt gränssnitt för att välja och skapa dokument via systemdialogrutan. SAF abstraherar den fysiska platsen för filer: appen vet inte varifrån filen läses — från den lokala disken, Google Drive eller Dropbox.

Arkitekturen för SAF omfattar tre komponenter: klientappen som initierar begäran, systemväljaren — standarddialogrutan för filval, och DocumentProvider — innehållsleverantören som implementerar åtkomst till filer i en specifik lagring. Användaren ser ett enhetligt gränssnitt oavsett datakälla.

SAF är tillgängligt från Android 4.4 (API 19). Ursprungligen stödde ramverket endast dokument, men i Android 5.0 lades stöd för kataloger till via ACTION_OPEN_DOCUMENT_TREE. Från och med Android 10 blev SAF den rekommenderade metoden för åtkomst till alla filer utanför app-specific storage.

Hur SAF fungerar: systemväljare och URI

SAF startar systemets dialogruta för filval via en Intent med åtgärden ACTION_OPEN_DOCUMENT. Användaren ser en lista över tillgängliga källor: intern lagring, Google Drive, Dropbox och andra registrerade leverantörer. Efter att ha valt en fil returnerar systemet en content URI med tillfälliga åtkomsträttigheter.

Content URI har formatet content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Till skillnad från file:// URI avslöjar content URI inte den verkliga sökvägen till filen och fungerar via DocumentProvider. Appen läser filen via ContentResolver.openInputStream baserat på den mottagna URI:n.

Systemväljaren stöder automatiskt sökning, sortering och filtrering av filer efter MIME-typer. Utvecklaren anger de nödvändiga typerna via Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), och väljaren visar endast relevanta filer.

Livscykel för URI-åtkomst

Som standard är URI:n giltig till omstart av appen eller omstart av enheten. För långsiktig åtkomst begär appen takePersistableUriPermission — detta gör det möjligt att läsa filen vid efterföljande start utan att välja om via dialogrutan.

ACTION_OPEN_DOCUMENT och ACTION_CREATE_DOCUMENT

SAF tillhandahåller tre huvudsakliga åtgärder för att arbeta med filer: öppna, skapa och välja mappträd. ACTION_OPEN_DOCUMENT öppnar systemväljaren för att välja en befintlig fil. ACTION_CREATE_DOCUMENT skapar en ny fil — användaren anger namnet i dialogrutan och appen får en URI för skrivning.

ACTION_OPEN_DOCUMENT_TREE gör det möjligt att välja en hel katalog och få åtkomst till alla filer i den. Det används i filhanterare, säkerhetskopierings- och synkroniseringsappar. Appen får katalogens URI och kan rekursivt lista innehållet via DocumentFile.

För varje åtgärd anges MIME-typer via EXTRA_MIME_TYPES. Flera typer kan anges: "application/pdf", "image/*", "text/plain". Om inga typer anges visar väljaren alla filer.

Persistent URI permissions

Persistent URI permissions — SAF-mekanism som gör det möjligt att behålla åtkomst till filen efter att den aktuella sessionen avslutats. Utan denna flagga är URI:n endast giltig till omstart av appen. Appen begär flaggan FLAG_GRANT_PERSISTABLE_URI_PERMISSION tillsammans med READ- och WRITE-flaggorna.

För att behålla rättigheter används metoden ContentResolver.takePersistableUriPermission. Systemet lagrar URI:n i ett särskilt register och återställer åtkomsten vid nästa start av appen. För att kontrollera om appen har bestående åtkomst till URI:n används ContentResolver.persistedUriPermissions.

Användaren kan återkalla sparade behörigheter via Inställningar → Appar → Behörigheter. Appen bör hantera scenariot när åtkomsten till filen oväntat försvinner. Det rekommenderas att kontrollera åtkomst via ContentResolver.openInputStream innan arbetet påbörjas och korrekt hantera SecurityException.

Kodexempel: välja fil via SAF

SAF startas via en standard Intent. Koden är minimal: skapa en Intent med ACTION_OPEN_DOCUMENT, ange MIME-typer och starta via ActivityResultContracts.StartActivityForResult. Efter att ha valt filen får callback URI:n i data.data, som sedan används för läsning.

val pickFile = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    result.data?.data?.let { uri ->
        val inputStream = contentResolver?.openInputStream(uri)
        // read from inputStream
    }
}

val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
    addCategory(Intent.CATEGORY_OPENABLE)
    setType("application/pdf")
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
}
pickFile.launch(intent)

Skapa fil via ACTION_CREATE_DOCUMENT

För att skriva en ny fil använd ACTION_CREATE_DOCUMENT. Intent accepterar MIME-typen och filnamnet via EXTRA_TITLE. Efter att ha valt mapp och bekräftat returnerar användaren en URI där appen skriver data via ContentResolver.openOutputStream. Systemet skapar automatiskt filen på den valda platsen.

SAF vs READ_EXTERNAL_STORAGE

SAF skiljer sig från traditionell READ_EXTERNAL_STORAGE genom ett fundamentalt annorlunda synsätt på säkerhet. Istället för att begära åtkomst till hela lagringen "på en gång" begär SAF endast åtkomst till en specifik fil. Detta minimerar attackytan och ökar användarens förtroende.

READ_EXTERNAL_STORAGE ger åtkomst till alla filer på enheten, inklusive foton och dokument från andra appar. På Android 10+ är denna metod begränsad. SAF å andra sidan ger endast åtkomst till filen som användaren valt och kräver uttrycklig bekräftelse för varje fil. För batchhantering av media, använd MediaStore; för enskilda dokument, använd SAF.

Den största nackdelen med SAF är att varje fil måste väljas separat. För massoperationer (säkerhetskopiering, mappsynkronisering) används ACTION_OPEN_DOCUMENT_TREE som ger åtkomst till alla filer i den valda katalogen. Lösningen beror på scenariot: SAF är optimalt för användarval, MediaStore för programmatisk åtkomst till media.