Dateien mit dem Storage Access Framework öffnen

Mit Android 4.4 (API-Level 19) wird das Storage Access Framework (SAF) eingeführt. Mit der SAF können Nutzer Dokumente, Bilder und andere Dateien auf allen ihren bevorzugten Anbietern für die Dokumentspeicherung suchen und öffnen. Eine standardmäßige, nutzerfreundliche UI ermöglicht es Nutzern, Dateien zu durchsuchen und auf die zuletzt verwendeten Dateien für alle Anwendungen und Anbieter einheitlich zuzugreifen.

Cloud- oder lokale Speicherdienste können an diesem System teilnehmen, indem sie einen DocumentsProvider implementieren, der ihre Dienste enthält. Clientanwendungen, die Zugriff auf die Dokumente eines Anbieters benötigen, können mit einigen wenigen Codezeilen in die SAF integriert werden.

Die SAF umfasst Folgendes:

  • Dokumentanbieter:Ein Inhaltsanbieter, mit dem ein Speicherdienst wie Google Drive die von ihm verwalteten Dateien anzeigen kann. Ein Dokumentanbieter wird als abgeleitete Klasse der DocumentsProvider-Klasse implementiert. Das Schema des Dokumentanbieters basiert auf einer herkömmlichen Dateihierarchie, wobei Sie selbst entscheiden, wie Ihr Dokumentanbieter Daten physisch speichert. Die Android-Plattform umfasst mehrere integrierte Dokumentanbieter wie Downloads, Bilder und Videos.
  • Client-App: Eine benutzerdefinierte App, die die Intent-Aktionen ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT und ACTION_OPEN_DOCUMENT_TREE aufruft und die von Dokumentanbietern zurückgegebenen Dateien empfängt.
  • Picker:Eine System-UI, mit der Nutzer auf Dokumente von allen Dokumentanbietern zugreifen können, die die Suchkriterien der Clientanwendung erfüllen.

SAF bietet folgende Funktionen:

  • Damit können Nutzer Inhalte von allen Dokumentanbietern durchsuchen, nicht nur aus einer einzelnen App.
  • Ermöglicht Ihrer Anwendung langfristigen, dauerhaften Zugriff auf Dokumente, die einem Dokumentanbieter gehören. Über diesen Zugriff können Nutzer Dateien beim Anbieter hinzufügen, bearbeiten, speichern und löschen.
  • Unterstützt mehrere Nutzerkonten und vorübergehende Root-Zertifikate, z. B. USB-Speicheranbieter, die nur angezeigt werden, wenn das Laufwerk angeschlossen ist.

Übersicht

Die SAF ist um einen Contentanbieter aufgebaut, der eine Unterklasse der DocumentsProvider-Klasse ist. Innerhalb eines Dokumentanbieters sind die Daten in einer traditionellen Dateihierarchie strukturiert:

Datenmodell

Abbildung 1: Datenmodell des Dokumentanbieters. Ein Stamm verweist auf ein einzelnes Dokument, das dann den Fan-Out des Baums startet.

Beachten Sie Folgendes:

  • Jeder Dokumentanbieter meldet einen oder mehrere Stammknoten, die als Ausgangspunkt zum Erkunden einer Dokumentstruktur dienen. Jeder Stamm hat eine eindeutige COLUMN_ROOT_ID und verweist auf ein Dokument (ein Verzeichnis), das den Inhalt unter diesem Stammverzeichnis darstellt. Roots sind dynamisch und unterstützen Anwendungsfälle wie mehrere Konten, temporäre USB-Speichergeräte oder die An- und Abmeldung von Nutzern.
  • Unter jedem Stamm befindet sich ein einzelnes Dokument. Dieses Dokument verweist auf 1 bis N Dokumente, von denen jedes wiederum auf 1 bis N Dokumente verweisen kann.
  • Jedes Speicher-Back-End ruft einzelne Dateien und Verzeichnisse auf, indem es mit einer eindeutigen COLUMN_DOCUMENT_ID darauf verweist. Dokument-IDs sind eindeutig und ändern sich nach der Ausgabe nicht, da sie für dauerhafte URI-Berechtigungen bei Geräteneustarts verwendet werden.
  • Dokumente können entweder eine öffnebare Datei mit einem bestimmten MIME-Typ oder ein Verzeichnis sein, das zusätzliche Dokumente mit dem MIME-Typ MIME_TYPE_DIR enthält.
  • Jedes Dokument kann unterschiedliche Berechtigungen haben, wie unter COLUMN_FLAGS beschrieben. Beispiel: FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE und FLAG_SUPPORTS_THUMBNAIL. Derselbe COLUMN_DOCUMENT_ID kann in mehreren Verzeichnissen enthalten sein.

Ablaufsteuerung

Das Datenmodell des Dokumentanbieters basiert auf einer herkömmlichen Dateihierarchie. Allerdings können Sie Ihre Daten so speichern, wie Sie möchten, solange Sie über die DocumentsProvider API darauf zugreifen können. Sie können beispielsweise Tag-basierten Cloud-Speicher für Ihre Daten verwenden.

Abbildung 2 zeigt, wie eine Foto-App mithilfe von SAF auf gespeicherte Daten zugreifen kann:

App

Abbildung 2: Storage Access Framework-Vorgang.

Beachten Sie Folgendes:

  • In der SAF interagieren Anbieter und Kunden nicht direkt. Ein Client fordert die Berechtigung zum Interagieren mit Dateien an, d. h. zum Lesen, Bearbeiten, Erstellen oder Löschen von Dateien.
  • Die Interaktion beginnt, wenn eine Anwendung, in diesem Beispiel eine Foto-App, den Intent ACTION_OPEN_DOCUMENT oder ACTION_CREATE_DOCUMENT auslöst. Der Intent kann Filter enthalten, um die Kriterien weiter zu verfeinern, z. B. „Gib mir alle öffnebaren Dateien mit dem MIME-Typ ‚Image‘“.
  • Sobald der Intent ausgelöst wird, geht die Systemauswahl an jeden registrierten Anbieter und zeigt dem Nutzer die übereinstimmenden Inhaltsstämme an.
  • Die Auswahl bietet Nutzern eine Standardoberfläche für den Zugriff auf Dokumente, auch wenn die zugrunde liegenden Dokumentanbieter sehr unterschiedlich sind. Abbildung 2 zeigt beispielsweise einen Google Drive-, einen USB- und einen Cloud-Anbieter.

In Abbildung 3 wählt der Nutzer den Ordner „Downloads“ aus einer Auswahl aus, die bei einer Suche nach Bildern geöffnet wird. In der Auswahl werden auch alle Stammknoten angezeigt, die für die Client-App verfügbar sind.

Screenshot der Ordnerauswahl in der Systemauswahl

Abbildung 3: Die Auswahl zeigt den Ordner „Downloads“, der als Suchspeicherort ausgewählt ist.

Nachdem der Nutzer den Ordner „Downloads“ ausgewählt hat, werden die Bilder angezeigt. Abbildung 4 zeigt das Ergebnis dieses Prozesses. Der Nutzer kann jetzt auf die vom Anbieter und die Client-App unterstützte Weise mit den Bildern interagieren.

Screenshot des Ordners „Downloads“

Abbildung 4: Bilder, die im Ordner „Downloads“ gespeichert sind, wie in der Systemauswahl angezeigt.

Clientanwendung schreiben

Wenn Ihre App unter Android 4.3 und niedriger eine Datei aus einer anderen App abrufen soll, muss sie einen Intent wie ACTION_PICK oder ACTION_GET_CONTENT aufrufen. Die Nutzenden wählen dann eine einzelne App aus, aus der sie eine Datei auswählen. Die ausgewählte Anwendung muss eine Benutzeroberfläche bereitstellen, in der der Nutzer suchen und aus den verfügbaren Dateien auswählen kann.

Unter Android 4.4 (API-Level 19) und höher können Sie zusätzlich den Intent ACTION_OPEN_DOCUMENT verwenden. Dieser zeigt eine systemgesteuerte Auswahl-UI an, über die der Nutzer alle Dateien durchsuchen kann, die von anderen Apps zur Verfügung gestellt wurden. Über diese Benutzeroberfläche kann der Nutzer eine Datei aus einer der unterstützten Anwendungen auswählen.

Unter Android 5.0 (API-Level 21) und höher können Sie auch den Intent ACTION_OPEN_DOCUMENT_TREE verwenden. Damit kann der Nutzer ein Verzeichnis auswählen, auf das eine Client-App zugreifen kann.

Hinweis : ACTION_OPEN_DOCUMENT ist kein Ersatz für ACTION_GET_CONTENT. Welche Methode Sie verwenden, hängt von den Anforderungen Ihrer App ab:

  • Verwenden Sie ACTION_GET_CONTENT, wenn Ihre Anwendung Daten lesen oder importieren soll. Bei diesem Ansatz importiert die Anwendung eine Kopie der Daten, z. B. eine Bilddatei.
  • Verwenden Sie ACTION_OPEN_DOCUMENT, wenn Ihre Anwendung langfristigen, persistenten Zugriff auf Dokumente haben soll, die einem Dokumentanbieter gehören. Ein Beispiel ist eine Fotobearbeitungs-App, mit der Nutzer Bilder bearbeiten können, die in einem Dokumentanbieter gespeichert sind.

Weitere Informationen dazu, wie Sie über die Benutzeroberfläche der Systemauswahl nach Dateien und Verzeichnissen suchen können, finden Sie in der Anleitung zum Zugriff auf Dokumente und andere Dateien.

Weitere Informationen

Weitere Informationen zu Dokumentanbietern finden Sie in den folgenden Ressourcen:

Produktproben

Videos

Zurück
Creating a content provider
Weiter
Create a custom document provider