Über freigegebenen Speicher auf Dokumente und andere Dateien zugreifen

Auf Geräten mit Android 4.4 (API-Level 19) und höher kann Ihre App über das Storage Access Framework mit einem Dokumentenanbieter interagieren, einschließlich externer Speichervolumes und cloudbasierten Speichern. Mit diesem Framework können Nutzer über eine Systemauswahl einen Dokumentenanbieter und bestimmte Dokumente und andere Dateien auswählen, die Ihre App erstellen, öffnen oder ändern soll.

Da der Nutzer die Dateien oder Verzeichnisse auswählt, auf die Ihre App zugreifen kann, sind für diesen Mechanismus keine Systemberechtigungen erforderlich. Außerdem werden die Nutzerkontrolle und der Datenschutz verbessert. Außerdem verbleiben diese Dateien, die außerhalb eines app-spezifischen Verzeichnisses und außerhalb des Medienspeichers gespeichert sind, auf dem Gerät, nachdem Ihre App deinstalliert wurde.

Die Verwendung des Frameworks umfasst die folgenden Schritte:

1. Eine App ruft einen Intent auf, der eine speicherbezogene Aktion enthält. Diese Aktion entspricht einem bestimmten Anwendungsfall, den das Framework bietet.
2. Der Nutzer sieht eine Systemauswahl, mit der er einen Dokumentenanbieter durchsuchen und einen Speicherort oder ein Dokument auswählen kann, an dem die speicherbezogene Aktion ausgeführt wird.
3. Die App erhält Lese- und Schreibzugriff auf einen URI, der den ausgewählten Speicherort oder das ausgewählte Dokument des Nutzers darstellt. Mit diesem URI kann die App Vorgänge am ausgewählten Standort ausführen.

Hinweis: Wenn Ihre App auf Mediendateien zugreift, sollten Sie die Bildauswahl verwenden. Sie bietet eine praktische Oberfläche für den Zugriff auf Fotos und Videos.

Wenn Sie den Zugriff auf Mediendateien auf Geräten mit Android 9 (API-Level 28) oder niedriger unterstützen möchten, deklarieren Sie die Berechtigung READ_EXTERNAL_STORAGE und legen Sie maxSdkVersion auf 28 fest.

In diesem Leitfaden werden die verschiedenen Anwendungsfälle erläutert, die das Framework für die Arbeit mit Dateien und anderen Dokumenten unterstützt. Außerdem wird erläutert, wie Sie Vorgänge am vom Nutzer ausgewählten Standort ausführen.

Anwendungsfälle für den Zugriff auf Dokumente und andere Dateien

Das Storage Access Framework unterstützt die folgenden Anwendungsfälle für den Zugriff auf Dateien und andere Dokumente.

Neue Datei erstellen

Mit der Intent-Aktion ACTION_CREATE_DOCUMENT können Nutzer eine Datei an einem bestimmten Speicherort speichern.

Dokument oder Datei öffnen

Mit der Intent-Aktion ACTION_OPEN_DOCUMENT können Nutzer ein bestimmtes Dokument oder eine bestimmte Datei auswählen, die geöffnet werden soll.

Zugriff auf den Inhalt eines Verzeichnisses gewähren

Die Intent-Aktion ACTION_OPEN_DOCUMENT_TREE, die unter Android 5.0 (API-Level 21) und höher verfügbar ist, ermöglicht es Nutzern, ein bestimmtes Verzeichnis auszuwählen und Ihrer App Zugriff auf alle Dateien und Unterverzeichnisse in diesem Verzeichnis zu gewähren.

In den folgenden Abschnitten wird beschrieben, wie Sie die einzelnen Anwendungsfälle konfigurieren.

Neue Dateien erstellen

Verwenden Sie die Intent-Aktion ACTION_CREATE_DOCUMENT, um die Systemdateiauswahl zu laden und dem Nutzer die Möglichkeit zu geben, einen Speicherort für das Schreiben des Inhalts einer Datei auszuwählen. Dieser Vorgang ähnelt dem, der in den Dialogfeldern „Als Datei speichern“ anderer Betriebssysteme verwendet wird.

Hinweis : Mit ACTION_CREATE_DOCUMENT können Sie keine vorhandene Datei überschreiben. Wenn Ihre App versucht, eine Datei mit demselben Namen zu speichern, fügt das System am Ende des Dateinamens eine Zahl in Klammern hinzu.

Wenn Ihre App beispielsweise versucht, eine Datei namens confirmation.pdf in einem Verzeichnis zu speichern, das bereits eine Datei mit diesem Namen enthält, speichert das System die neue Datei mit dem Namen confirmation(1).pdf.

Geben Sie beim Konfigurieren des Intents den Namen und den MIME-Typ der Datei an und geben Sie optional den URI der Datei oder des Verzeichnisses an, das die Dateiauswahl beim ersten Laden anzeigen soll. Verwenden Sie dazu das Intent-Extra EXTRA_INITIAL_URI.

Das folgende Code-Snippet zeigt, wie der Intent zum Erstellen einer Datei erstellt und aufgerufen wird:

Kotlin

// Request code for creating a PDF document.
const val CREATE_FILE = 1

private fun createFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_CREATE_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"
        putExtra(Intent.EXTRA_TITLE, "invoice.pdf")

        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker before your app creates the document.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }
    startActivityForResult(intent, CREATE_FILE)
}

Java

// Request code for creating a PDF document.
private static final int CREATE_FILE = 1;

private void createFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");
    intent.putExtra(Intent.EXTRA_TITLE, "invoice.pdf");

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when your app creates the document.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, CREATE_FILE);
}

Datei öffnen

Ihre App verwendet möglicherweise Dokumente als Speichereinheit, in die Nutzer Daten eingeben, die sie mit anderen teilen oder in andere Dokumente importieren möchten. Beispiele hierfür sind ein Nutzer, der ein Produktivitätsdokument oder ein Buch öffnet, das als EPUB-Datei gespeichert ist.

Lassen Sie den Nutzer in diesen Fällen die zu öffnende Datei auswählen, indem Sie den Intent ACTION_OPEN_DOCUMENT aufrufen, wodurch die Dateiauswahl des Systems geöffnet wird. Geben Sie einen MIME-Typ an, um nur die Dateitypen anzuzeigen, die von Ihrer App unterstützt werden. Optional können Sie mit dem Intent-Extra EXTRA_INITIAL_URI den URI der Datei angeben, die beim ersten Laden in der Dateiauswahl angezeigt werden soll.

Das folgende Code-Snippet zeigt, wie der Intent zum Öffnen eines PDF-Dokuments erstellt und aufgerufen wird:

Kotlin

// Request code for selecting a PDF document.
const val PICK_PDF_FILE = 2

fun openFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"

        // Optionally, specify a URI for the file that should appear in the
        // system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent, PICK_PDF_FILE)
}

Java

// Request code for selecting a PDF document.
private static final int PICK_PDF_FILE = 2;

private void openFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");

    // Optionally, specify a URI for the file that should appear in the
    // system file picker when it loads.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, PICK_PDF_FILE);
}

Zugriffsbeschränkungen

Unter Android 11 (API-Level 30) und höher können Sie die Intent-Aktion ACTION_OPEN_DOCUMENT nicht verwenden, um den Nutzer aufzufordern, einzelne Dateien aus den folgenden Verzeichnissen auszuwählen:

• Das Verzeichnis Android/data/ und alle Unterverzeichnisse
• Das Verzeichnis Android/obb/ und alle Unterverzeichnisse

Zugriff auf den Inhalt eines Verzeichnisses gewähren

Hinweis :Die in diesem Abschnitt beschriebene Intent-Aktion ist ab Android 5.0 (API-Level 21) verfügbar.

Dateiverwaltungs- und Medienerstellungs-Apps verwalten in der Regel Dateigruppen in einer Verzeichnishierarchie. Wenn Sie diese Funktion in Ihrer App anbieten möchten, verwenden Sie die Intent-Aktion ACTION_OPEN_DOCUMENT_TREE. Damit kann der Nutzer mit einigen Ausnahmen ab Android 11 (API-Level 30) Zugriff auf einen gesamten Verzeichnisbaum gewähren. Ihre App kann dann auf jede Datei im ausgewählten Verzeichnis und in seinen Unterverzeichnissen zugreifen.

Wenn Sie ACTION_OPEN_DOCUMENT_TREE verwenden, erhält Ihre App nur Zugriff auf die Dateien im Verzeichnis, das der Nutzer auswählt. Sie haben keinen Zugriff auf Dateien anderer Apps, die sich außerhalb dieses vom Nutzer ausgewählten Verzeichnisses befinden. Mit diesem nutzergesteuerten Zugriff können Nutzer genau auswählen, welche Inhalte sie für Ihre App freigeben möchten.

Optional können Sie mit dem Intent-Extra EXTRA_INITIAL_URI den URI des Verzeichnisses angeben, das in der Dateiauswahl angezeigt werden soll, wenn sie zum ersten Mal geladen wird.

Das folgende Code-Snippet zeigt, wie der Intent zum Öffnen eines Verzeichnisses erstellt und aufgerufen wird:

Kotlin

fun openDirectory(pickerInitialUri: Uri) {
    // Choose a directory using the system's file picker.
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply {
        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent, your-request-code)
}

Java

public void openDirectory(Uri uriToLoad) {
    // Choose a directory using the system's file picker.
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when it loads.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, uriToLoad);

    startActivityForResult(intent, your-request-code);
}

Achtung: Wenn Sie eine große Anzahl von Dateien im Verzeichnis durchgehen, auf das über ACTION_OPEN_DOCUMENT_TREE zugegriffen wird, kann die Leistung Ihrer App beeinträchtigt werden.

Zugriffsbeschränkungen

Unter Android 11 (API-Level 30) und höher können Sie die Intent-Aktion ACTION_OPEN_DOCUMENT_TREE nicht verwenden, um Zugriff auf die folgenden Verzeichnisse anzufordern:

• Das Stammverzeichnis des internen Speichervolumes.
• Das Stammverzeichnis jedes SD-Kartenvolumes, das vom Gerätehersteller als zuverlässig eingestuft wird, unabhängig davon, ob die Karte emuliert oder herausnehmbar ist. Ein zuverlässiges Volume ist ein Volume, auf das eine App die meiste Zeit erfolgreich zugreifen kann.
• Das Verzeichnis Download.

Außerdem können Sie unter Android 11 (API-Level 30) und höher nicht über die Intent-Aktion ACTION_OPEN_DOCUMENT_TREE den Nutzer auffordern, einzelne Dateien aus den folgenden Verzeichnissen auszuwählen:

• Das Verzeichnis Android/data/ und alle Unterverzeichnisse
• Das Verzeichnis Android/obb/ und alle Unterverzeichnisse

Vorgänge für den ausgewählten Standort ausführen

Nachdem der Nutzer eine Datei oder ein Verzeichnis über die Dateiauswahl des Systems ausgewählt hat, können Sie den URI des ausgewählten Elements mit dem folgenden Code in onActivityResult() abrufen:

Kotlin

override fun onActivityResult(
        requestCode: Int, resultCode: Int, resultData: Intent?) {
    if (requestCode == your-request-code
            && resultCode == Activity.RESULT_OK) {
        // The result data contains a URI for the document or directory that
        // the user selected.
        resultData?.data?.also { uri ->
            // Perform operations on the document using its URI.
        }
    }
}

Java

@Override
public void onActivityResult(int requestCode, int resultCode,
        Intent resultData) {
    if (requestCode == your-request-code
            && resultCode == Activity.RESULT_OK) {
        // The result data contains a URI for the document or directory that
        // the user selected.
        Uri uri = null;
        if (resultData != null) {
            uri = resultData.getData();
            // Perform operations on the document using its URI.
        }
    }
}

Wenn Sie einen Verweis auf den URI des ausgewählten Elements abrufen, kann Ihre App mehrere Vorgänge auf dem Element ausführen. Sie können beispielsweise auf die Metadaten des Elements zugreifen, das Element an Ort und Stelle bearbeiten und es löschen.

In den folgenden Abschnitten wird beschrieben, wie Sie Aktionen an den vom Nutzer ausgewählten Dateien ausführen.

Von einem Anbieter unterstützte Vorgänge ermitteln

Unterschiedliche Inhaltsanbieter ermöglichen unterschiedliche Aktionen an Dokumenten, z. B. das Kopieren des Dokuments oder das Ansehen der Miniaturansicht eines Dokuments. Welche Vorgänge ein bestimmter Anbieter unterstützt, geht aus dem Wert von Document.COLUMN_FLAGS hervor. Die Benutzeroberfläche Ihrer App kann dann nur die Optionen anzeigen, die der Anbieter unterstützt.

Berechtigungen dauerhaft speichern

Wenn Ihre App eine Datei zum Lesen oder Schreiben öffnet, gewährt das System Ihrer App eine URI-Berechtigung für diese Datei, die bis zum Neustart des Geräts des Nutzers gültig ist. Angenommen, Ihre App ist eine Bildbearbeitungs-App und Sie möchten, dass Nutzer direkt über Ihre App auf die fünf zuletzt bearbeiteten Bilder zugreifen können. Wenn das Gerät des Nutzers neu gestartet wurde, müssten Sie ihn zur Systemauswahl zurücksenden, um die Dateien zu finden.

Damit der Zugriff auf Dateien nach einem Neustart des Geräts erhalten bleibt und die Nutzerfreundlichkeit verbessert wird, kann Ihre App die vom System angebotene dauerhafte URI-Berechtigung annehmen, wie im folgenden Code-Snippet gezeigt:

Kotlin

val contentResolver = applicationContext.contentResolver

val takeFlags: Int = Intent.FLAG_GRANT_READ_URI_PERMISSION or
        Intent.FLAG_GRANT_WRITE_URI_PERMISSION
// Check for the freshest data.
contentResolver.takePersistableUriPermission(uri, takeFlags)

Java

final int takeFlags = intent.getFlags()
            & (Intent.FLAG_GRANT_READ_URI_PERMISSION
            | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
// Check for the freshest data.
getContentResolver().takePersistableUriPermission(uri, takeFlags);

Achtung :Auch nach dem Aufruf von takePersistableUriPermission() behält Ihre App keinen Zugriff auf den URI, wenn das zugehörige Dokument verschoben oder gelöscht wird. In diesen Fällen musst du noch einmal um Erlaubnis bitten, um wieder Zugriff auf den URI zu erhalten.

Dokumentmetadaten prüfen

Wenn Sie den URI für ein Dokument haben, erhalten Sie Zugriff auf die zugehörigen Metadaten. Dieses Snippet ruft die Metadaten für ein Dokument ab, das durch den URI angegeben ist, und protokolliert sie:

Kotlin

val contentResolver = applicationContext.contentResolver

fun dumpImageMetaData(uri: Uri) {

    // The query, because it only applies to a single document, returns only
    // one row. There's no need to filter, sort, or select fields,
    // because we want all fields for one document.
    val cursor: Cursor? = contentResolver.query(
            uri, null, null, null, null, null)

    cursor?.use {
        // moveToFirst() returns false if the cursor has 0 rows. Very handy for
        // "if there's anything to look at, look at it" conditionals.
        if (it.moveToFirst()) {

            // Note it's called "Display Name". This is
            // provider-specific, and might not necessarily be the file name.
            val displayName: String =
                    it.getString(it.getColumnIndex(OpenableColumns.DISPLAY_NAME))
            Log.i(TAG, "Display Name: $displayName")

            val sizeIndex: Int = it.getColumnIndex(OpenableColumns.SIZE)
            // If the size is unknown, the value stored is null. But because an
            // int can't be null, the behavior is implementation-specific,
            // and unpredictable. So as
            // a rule, check if it's null before assigning to an int. This will
            // happen often: The storage API allows for remote files, whose
            // size might not be locally known.
            val size: String = if (!it.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                it.getString(sizeIndex)
            } else {
                "Unknown"
            }
            Log.i(TAG, "Size: $size")
        }
    }
}

Java

public void dumpImageMetaData(Uri uri) {

    // The query, because it only applies to a single document, returns only
    // one row. There's no need to filter, sort, or select fields,
    // because we want all fields for one document.
    Cursor cursor = getActivity().getContentResolver()
            .query(uri, null, null, null, null, null);

    try {
        // moveToFirst() returns false if the cursor has 0 rows. Very handy for
        // "if there's anything to look at, look at it" conditionals.
        if (cursor != null && cursor.moveToFirst()) {

            // Note it's called "Display Name". This is
            // provider-specific, and might not necessarily be the file name.
            String displayName = cursor.getString(
                    cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME));
            Log.i(TAG, "Display Name: " + displayName);

            int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
            // If the size is unknown, the value stored is null. But because an
            // int can't be null, the behavior is implementation-specific,
            // and unpredictable. So as
            // a rule, check if it's null before assigning to an int. This will
            // happen often: The storage API allows for remote files, whose
            // size might not be locally known.
            String size = null;
            if (!cursor.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                size = cursor.getString(sizeIndex);
            } else {
                size = "Unknown";
            }
            Log.i(TAG, "Size: " + size);
        }
    } finally {
        cursor.close();
    }
}

Dokument öffnen

Wenn Sie einen Verweis auf den URI eines Dokuments haben, können Sie es zur weiteren Verarbeitung öffnen. In diesem Abschnitt finden Sie Beispiele zum Öffnen einer Bitmap und eines Eingabestreams.

Bitmap

Im folgenden Code-Snippet wird gezeigt, wie eine Bitmap-Datei anhand ihres URI geöffnet wird:

Kotlin

val contentResolver = applicationContext.contentResolver

@Throws(IOException::class)
private fun getBitmapFromUri(uri: Uri): Bitmap {
    val parcelFileDescriptor: ParcelFileDescriptor =
            contentResolver.openFileDescriptor(uri, "r")
    val fileDescriptor: FileDescriptor = parcelFileDescriptor.fileDescriptor
    val image: Bitmap = BitmapFactory.decodeFileDescriptor(fileDescriptor)
    parcelFileDescriptor.close()
    return image
}

Java

private Bitmap getBitmapFromUri(Uri uri) throws IOException {
    ParcelFileDescriptor parcelFileDescriptor =
            getContentResolver().openFileDescriptor(uri, "r");
    FileDescriptor fileDescriptor = parcelFileDescriptor.getFileDescriptor();
    Bitmap image = BitmapFactory.decodeFileDescriptor(fileDescriptor);
    parcelFileDescriptor.close();
    return image;
}

Hinweis: Dieser Vorgang sollte in einem Hintergrund- und nicht im UI-Thread ausgeführt werden.

Nachdem Sie die Bitmap geöffnet haben, können Sie sie in einem ImageView anzeigen.

Eingabestream

Im folgenden Code-Snippet wird gezeigt, wie ein InputStream-Objekt anhand seiner URI geöffnet wird. In diesem Snippet werden die Zeilen der Datei in einen String gelesen:

Kotlin

val contentResolver = applicationContext.contentResolver

@Throws(IOException::class)
private fun readTextFromUri(uri: Uri): String {
    val stringBuilder = StringBuilder()
    contentResolver.openInputStream(uri)?.use { inputStream ->
        BufferedReader(InputStreamReader(inputStream)).use { reader ->
            var line: String? = reader.readLine()
            while (line != null) {
                stringBuilder.append(line)
                line = reader.readLine()
            }
        }
    }
    return stringBuilder.toString()
}

Java

private String readTextFromUri(Uri uri) throws IOException {
    StringBuilder stringBuilder = new StringBuilder();
    try (InputStream inputStream =
            getContentResolver().openInputStream(uri);
            BufferedReader reader = new BufferedReader(
            new InputStreamReader(Objects.requireNonNull(inputStream)))) {
        String line;
        while ((line = reader.readLine()) != null) {
            stringBuilder.append(line);
        }
    }
    return stringBuilder.toString();
}

Dokumente bearbeiten

Mit dem Storage Access Framework können Sie ein Textdokument direkt bearbeiten.

Hinweis: Die Methode canWrite() der Klasse DocumentFile gibt nicht unbedingt an, dass Ihre App ein Dokument bearbeiten kann. Das liegt daran, dass diese Methode true zurückgibt, wenn Document.COLUMN_FLAGS entweder FLAG_SUPPORTS_DELETE oder FLAG_SUPPORTS_WRITE enthält. Wenn Sie wissen möchten, ob Ihre App ein bestimmtes Dokument bearbeiten kann, fragen Sie den Wert von FLAG_SUPPORTS_WRITE direkt ab.

Im folgenden Code-Snippet wird der Inhalt des Dokuments überschrieben, das durch den angegebenen URI dargestellt wird:

Kotlin

val contentResolver = applicationContext.contentResolver

private fun alterDocument(uri: Uri) {
    try {
        contentResolver.openFileDescriptor(uri, "w")?.use {
            FileOutputStream(it.fileDescriptor).use {
                it.write(
                    ("Overwritten at ${System.currentTimeMillis()}\n")
                        .toByteArray()
                )
            }
        }
    } catch (e: FileNotFoundException) {
        e.printStackTrace()
    } catch (e: IOException) {
        e.printStackTrace()
    }
}

Java

private void alterDocument(Uri uri) {
    try {
        ParcelFileDescriptor pfd = getActivity().getContentResolver().
                openFileDescriptor(uri, "w");
        FileOutputStream fileOutputStream =
                new FileOutputStream(pfd.getFileDescriptor());
        fileOutputStream.write(("Overwritten at " + System.currentTimeMillis() +
                "\n").getBytes());
        // Let the document provider know you're done by closing the stream.
        fileOutputStream.close();
        pfd.close();
    } catch (FileNotFoundException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

Dokument löschen

Wenn Sie den URI für ein Dokument haben und die Document.COLUMN_FLAGS des Dokuments SUPPORTS_DELETE enthält, können Sie das Dokument löschen. Beispiel:

Kotlin

DocumentsContract.deleteDocument(applicationContext.contentResolver, uri)

Java

DocumentsContract.deleteDocument(applicationContext.contentResolver, uri);

Äquivalente Medien-URI abrufen

Die Methode getMediaUri() liefert einen URI für einen Medienspeicher, der dem angegebenen URI des Dokumentanbieters entspricht. Die beiden URIs verweisen auf dasselbe zugrunde liegende Element. Mit dem URI des Medienspeichers können Sie einfacher auf Mediendateien aus freigegebenem Speicher zugreifen.

Hinweis :Mit dieser Methode werden keine neuen Berechtigungen gewährt. Ihre App muss bereits über die erforderlichen Berechtigungen für den Zugriff auf einen bestimmten URI des Dokumentanbieters verfügen, z. B. durch Öffnen des Dokuments.

Die getMediaUri()-Methode unterstützt ExternalStorageProvider-URIs. Unter Android 12 (API-Level 31) und höher unterstützt die Methode auch MediaDocumentsProvider-URIs.

Virtuelle Datei öffnen

Unter Android 7.0 (API-Level 25) und höher kann Ihre App virtuelle Dateien verwenden, die vom Storage Access Framework bereitgestellt werden. Auch wenn virtuelle Dateien keine binäre Darstellung haben, kann Ihre App ihren Inhalt öffnen, indem sie in einen anderen Dateityp umgewandelt oder mithilfe der Intent-Aktion ACTION_VIEW angezeigt werden.

Damit virtuelle Dateien geöffnet werden können, muss Ihre Clientanwendung eine spezielle Logik zum Umgang mit ihnen enthalten. Wenn Sie eine Bytedarstellung der Datei erhalten möchten, z. B. für eine Vorschau, müssen Sie beim Dokumentanbieter einen alternativen MIME-Typ anfordern.

Hinweis: Da eine App eine virtuelle Datei nicht direkt mit der Methode openInputStream() öffnen kann, verwenden Sie beim Erstellen des Intents, der die Aktion ACTION_OPEN_DOCUMENT oder ACTION_OPEN_DOCUMENT_TREE enthält, nicht die Kategorie CATEGORY_OPENABLE.

Nachdem der Nutzer eine Auswahl getroffen hat, kannst du anhand des URI in den Ergebnisdaten feststellen, ob die Datei virtuell ist, wie im folgenden Code-Snippet gezeigt:

Kotlin

private fun isVirtualFile(uri: Uri): Boolean {
    if (!DocumentsContract.isDocumentUri(this, uri)) {
        return false
    }

    val cursor: Cursor? = contentResolver.query(
            uri,
            arrayOf(DocumentsContract.Document.COLUMN_FLAGS),
            null,
            null,
            null
    )

    val flags: Int = cursor?.use {
        if (cursor.moveToFirst()) {
            cursor.getInt(0)
        } else {
            0
        }
    } ?: 0

    return flags and DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT != 0
}

Java

private boolean isVirtualFile(Uri uri) {
    if (!DocumentsContract.isDocumentUri(this, uri)) {
        return false;
    }

    Cursor cursor = getContentResolver().query(
        uri,
        new String[] { DocumentsContract.Document.COLUMN_FLAGS },
        null, null, null);

    int flags = 0;
    if (cursor.moveToFirst()) {
        flags = cursor.getInt(0);
    }
    cursor.close();

    return (flags & DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT) != 0;
}

Nachdem Sie bestätigt haben, dass es sich bei dem Dokument um eine virtuelle Datei handelt, können Sie die Datei zu einem alternativen MIME-Typ wie "image/png" zwingen. Im folgenden Code-Snippet wird gezeigt, wie geprüft wird, ob eine virtuelle Datei als Bild dargestellt werden kann, und falls ja, wird ein Eingabestream aus der virtuellen Datei abgerufen:

Kotlin

@Throws(IOException::class)
private fun getInputStreamForVirtualFile(
        uri: Uri, mimeTypeFilter: String): InputStream {

    val openableMimeTypes: Array<String>? =
            contentResolver.getStreamTypes(uri, mimeTypeFilter)

    return if (openableMimeTypes?.isNotEmpty() == true) {
        contentResolver
                .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null)
                .createInputStream()
    } else {
        throw FileNotFoundException()
    }
}

Java

private InputStream getInputStreamForVirtualFile(Uri uri, String mimeTypeFilter)
    throws IOException {

    ContentResolver resolver = getContentResolver();

    String[] openableMimeTypes = resolver.getStreamTypes(uri, mimeTypeFilter);

    if (openableMimeTypes == null ||
        openableMimeTypes.length < 1) {
        throw new FileNotFoundException();
    }

    return resolver
        .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null)
        .createInputStream();
}

Weitere Informationen

Weitere Informationen zum Speichern und Abrufen von Dokumenten und anderen Dateien finden Sie in den folgenden Ressourcen.

Produktproben

• ActionOpenDocument, verfügbar auf GitHub
• ActionOpenDocumentTree, verfügbar auf GitHub.

Videos

• Vorbereitung auf den abgestuften Speicher (Android Dev Summit '19)