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
iACTION_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:
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ładFLAG_SUPPORTS_WRITE
,FLAG_SUPPORTS_DELETE
iFLAG_SUPPORTS_THUMBNAIL
. Ten sam elementCOLUMN_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:
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
lubACTION_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.
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ą.
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.
Uwaga: ACTION_OPEN_DOCUMENT
nie zastępuje ACTION_GET_CONTENT
.
To, którego użyjesz, zależy od potrzeb aplikacji:
- Użyj
ACTION_GET_CONTENT
, jeśli chcesz, by aplikacja odczytywała lub importowała dane. W tym przypadku aplikacja importuje kopię danych, np. plik graficzny. - Użyj
ACTION_OPEN_DOCUMENT
, jeśli chcesz, aby Twoja aplikacja miała długoterminowy, trwały dostęp do dokumentów należących do dostawcy dokumentów. Przykładem może być aplikacja do edycji zdjęć, która pozwala edytować obrazy zapisane u dostawcy dokumentów.
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
Filmy
- DevBytes: platforma dostępu do miejsca na dane w Androidzie 4.4: dostawca
- Pliki wirtualne w platformie Storage Access Framework