Otwieranie plików za pomocą Storage Access Framework

Android 4.4 (poziom interfejsu API 19) wprowadza platformę Storage Access Framework (SAF). Platforma SAF umożliwia użytkownikom przeglądanie i otwieranie dokumentów, obrazów i innych plików u wszystkich preferowanych dostawców usług przechowywania dokumentów. Standardowy, łatwy w obsłudze interfejs ułatwia przeglądanie i otwieranie ostatnich plików w spójny sposób w różnych aplikacjach i u dostawców.

Usługi pamięci masowej w chmurze lub w środowisku lokalnym mogą uczestniczyć w tym ekosystemie, implementując DocumentsProvider, który obejmuje ich usługi. Aplikacje klienckie, które potrzebują dostępu do dokumentów dostawcy, mogą zintegrować z SAF za pomocą kilku wierszy kodu.

SAF obejmuje:

• Dostawca dokumentów: dostawca treści, który umożliwia usłudze przechowywania danych (np. Dysk Google) ujawnianie plików, którymi zarządza. Dostawca dokumentu jest zaimplementowany jako podklasa klasy DocumentsProvider. Schemat dostawcy dokumentów opiera się na tradycyjnej hierarchii plików, ale to Ty decydujesz, jak dostawca dokumentów fizycznie przechowuje dane. Platforma Android oferuje kilku wbudowanych dostawców dokumentów, takich jak Pobieranie, Grafika i Filmy.
• Aplikacja kliencka: niestandardowa aplikacja, która wywołuje działania intencji ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT i ACTION_OPEN_DOCUMENT_TREE oraz odbiera pliki zwrócone przez dostawców dokumentów.
• Wybór: interfejs systemu, który umożliwia użytkownikom dostęp do dokumentów od wszystkich dostawców dokumentów spełniających kryteria wyszukiwania aplikacji klienckiej.

Konto SAF oferuje następujące funkcje:

• Pozwala użytkownikom przeglądać treści od wszystkich dostawców dokumentów, a nie tylko z jednej aplikacji.
• Umożliwia aplikacji długoterminowy, trwały dostęp do dokumentów należących do dostawcy dokumentów. Użytkownicy z tym dostępem mogą dodawać, edytować, zapisywać i usuwać pliki u dostawcy.
• Obsługuje wiele kont użytkowników i tymczasowych katalogów głównych, takich jak dostawcy pamięci USB, które są widoczne tylko wtedy, gdy dysk jest podłączony.

Przegląd

SAF skupia się wokół dostawcy treści, który jest podklasą klasy DocumentsProvider. Dane dostawcy dokumentów mają tradycyjną hierarchię plików:

Rysunek 1. Model danych dostawcy dokumentu. Pierwiastek wskazuje pojedynczy dokument, który następnie zaczyna się rozchodzić z drzewa.

Uwaga:

• Każdy dostawca dokumentów zgłasza co najmniej jeden katalog główny, który jest punktem wyjścia do eksploracji drzewa dokumentów. Każdy katalog główny ma unikalny element COLUMN_ROOT_ID, który wskazuje dokument (katalog) reprezentujący zawartość tego katalogu. Katalogi główne są z założenia dynamiczne, więc obsługują wiele kont, tymczasowe urządzenia pamięci USB oraz logowanie i wylogowywanie się użytkownika.
• Każdy element główny to pojedynczy dokument. Dokument ten wskazuje od 1 do N dokumentów, z których każdy może wskazywać od 1 do N.
• Każdy backend pamięci masowej wyświetla poszczególne pliki i katalogi, odwołując się do nich za pomocą unikalnego identyfikatora COLUMN_DOCUMENT_ID. Identyfikatory dokumentów są unikalne i nie zmieniają się po wystawieniu, ponieważ są używane do trwałego przyznawania identyfikatora URI podczas ponownego uruchamiania urządzenia.
• Dokumenty mogą być otwartymi plikami o określonym typie MIME lub katalogiem zawierającym dodatkowe dokumenty z typem MIME MIME_TYPE_DIR.
• Każdy dokument może mieć różne możliwości, zgodnie z opisem w COLUMN_FLAGS. na przykład FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE i FLAG_SUPPORTS_THUMBNAIL. Ten sam element COLUMN_DOCUMENT_ID może znajdować się w kilku katalogach.

Sterowanie przepływem

Model danych dostawcy dokumentu opiera się na tradycyjnej hierarchii plików. Możesz jednak przechowywać dane w dowolny sposób, o ile masz do nich dostęp za pomocą interfejsu API DocumentsProvider. Możesz na przykład przechowywać dane w chmurze na podstawie tagów.

Rysunek 2 przedstawia, jak aplikacja do zdjęć może korzystać z SAF do uzyskiwania dostępu do zapisanych danych:

Rysunek 2. Przepływ platformy Storage Access Framework.

Uwaga:

• W SAF usługodawcy i klienci nie kontaktują się bezpośrednio ze sobą. Klient prosi o uprawnienia do interakcji z plikami, czyli do odczytu, edycji, tworzenia i usuwania plików.
• Interakcja rozpoczyna się, gdy aplikacja (w tym przykładzie jest to aplikacja do obsługi zdjęć) uruchomi intencję ACTION_OPEN_DOCUMENT lub ACTION_CREATE_DOCUMENT. Intencja może zawierać filtry pozwalające zawęzić kryteria, np. „podać wszystkie możliwe do otwarcia pliki, które mają typ MIME „obraz”.
• Po uruchomieniu intencji selektor systemowy przejdzie do każdego zarejestrowanego dostawcy i wyświetli użytkownikowi pasujące treści główne.
• Selektor zapewnia użytkownikom standardowy interfejs do uzyskiwania dostępu do dokumentów nawet wtedy, gdy dostawcy dokumentów bardzo się różnią. Na przykład na rysunku 2 widać dostawcę Dysku Google, dostawcę USB i dostawcę chmury.

Na ilustracji 3 użytkownik wybiera folder Pobrane z selektora otwartego w wyszukiwarce obrazów. Selektor pokazuje też wszystkie katalogi główne dostępne dla aplikacji klienckiej.

Rysunek 3. Selektor, który pokazuje folder Pobrane jako lokalizację wyszukiwania.

Gdy użytkownik wybierze folder Pobrane pliki, obrazy zostaną wyświetlone. Rezultat tego procesu jest widoczny na Rysunku 4. Użytkownik może teraz wchodzić w interakcje z obrazami w sposób obsługiwany przez dostawcę i aplikację kliencką.

Rysunek 4. Obrazy przechowywane w folderze Pobrane pliki widoczne w selektorze systemowym.

Pisanie aplikacji klienckiej

Jeśli na Androidzie 4.3 i starszych wersjach aplikacja ma pobierać plik z innej aplikacji, musi wywołać intencję taką jak ACTION_PICK lub ACTION_GET_CONTENT. Następnie wybiera jedną aplikację, z której ma wybrać plik. Wybrana aplikacja musi zapewniać interfejs, który umożliwia użytkownikowi przeglądanie i wybieranie dostępnych plików.

W Androidzie 4.4 (poziom interfejsu API 19) i nowszych dostępna jest dodatkowa opcja użycia intencji ACTION_OPEN_DOCUMENT, która wyświetla sterowany przez system interfejs selektora, który umożliwia użytkownikowi przeglądanie wszystkich plików udostępnionych przez inne aplikacje. W tym interfejsie użytkownik może wybrać plik z dowolnej z obsługiwanych aplikacji.

W Androidzie 5.0 (poziom interfejsu API 21) i nowszych możesz też użyć intencji ACTION_OPEN_DOCUMENT_TREE, która pozwala użytkownikowi wybrać katalog, do którego będzie uzyskiwać dostęp aplikacja kliencka.

Więcej informacji o obsłudze przeglądania plików i katalogów za pomocą interfejsu selektora systemowego znajdziesz w przewodniku o dostępie do dokumentów i innych plików.

Dodatkowe materiały

Aby dowiedzieć się więcej o dostawcach dokumentów, skorzystaj z tych materiałów:

Próbki

• StorageProvider

Filmy

• DevBytes: platforma dostępu do miejsca na dane w Androidzie 4.4: dostawca
• Pliki wirtualne w platformie Storage Access Framework