Ta strona została przetłumaczona przez Cloud Translation API.

Otwieranie plików za pomocą Storage Access Framework
Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Android 4.4 (poziom interfejsu API 19) wprowadza interfejs Storage Access Framework (SAF). Platforma SAF umożliwia użytkownikom przeglądanie i otwieranie dokumentów, obrazów i innych plików w przypadku wszystkich preferowanych dostawców miejsca na dokumenty. Standardowy, łatwy w użyciu interfejs umożliwia użytkownikom przeglądanie plików i dostęp do ostatnich plików w sposób spójny w różnych aplikacjach i u różnych dostawców.

Usługi przechowywania w chmurze lub na urządzeniu lokalnym mogą uczestniczyć w tym ekosystemie dzięki wdrożeniu DocumentsProvider, który zawiera ich usługi. Aplikacje klienckie, które potrzebują dostępu do dokumentów dostawcy, mogą się z nim integrować za pomocą kilku linii kodu.

SAF obejmuje:

Dokument provider: dostawca treści, który umożliwia usłudze przechowywania danych, takiej jak Dysk Google, wyświetlanie plików, którymi zarządza. Dostawca dokumentu jest implementowany jako podklasa klasy DocumentsProvider. Schemat dostawcy dokumentów jest oparty na tradycyjnej hierarchii plików, ale to od Ciebie zależy, jak dostawca dokumentów będzie przechowywać dane. Platforma Android zawiera kilka wbudowanych dostawców dokumentów, takich jak Pobrane, Obrazy i Filmy.
Aplikacja kliencka: aplikacja niestandardowa, która wywołuje akcje intencyjne ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT i ACTION_OPEN_DOCUMENT_TREE oraz odbiera pliki zwracane przez dostawców dokumentów.
Selektor: interfejs systemu, który umożliwia użytkownikom dostęp do dokumentów od wszystkich dostawców dokumentów, którzy spełniają kryteria wyszukiwania aplikacji klienckiej.

SAF oferuje te funkcje:

Umożliwia użytkownikom przeglądanie treści od wszystkich dostawców dokumentów, a nie tylko z jednej aplikacji.
Umożliwia aplikacji długotrwały dostęp do dokumentów należących do dostawcy dokumentów. Dzięki temu użytkownicy mogą dodawać, edytować, zapisywać i usuwać pliki u dostawcy.
Obsługuje wiele kont użytkowników i tymczasowe katalogi główne, takie jak dostawcy pamięci USB, które są widoczne tylko wtedy, gdy dysk jest podłączony.

Omówienie

SAF koncentruje się na dostawcy treści, który jest podklasą klasy DocumentsProvider. W dostawcy dokumentów dane są ustrukturyzowane w tradycyjnej hierarchii plików:

**Rysunek 1.** Model danych dostawcy dokumentów. Element wierzchołkowy wskazuje na pojedynczy dokument, który rozpoczyna rozgałęzienie drzewa.

Uwaga:

Każdy dostawca dokumentów podaje co najmniej korzenie, czyli punkty początkowe służące do eksplorowania drzewa dokumentów. Każdy element wierzchołkowy ma unikalny identyfikator COLUMN_ROOT_ID, który wskazuje dokument (katalog) reprezentujący zawartość tego elementu wierzchołkowego. Z założenia są one dynamiczne, aby obsługiwać takie przypadki użycia jak wiele kont, przejściowe urządzenia pamięci masowej USB czy logowanie i wylogowywanie użytkowników.
Pod każdym elementem katalogu znajduje się pojedynczy dokument. Ten dokument wskazuje 1–N dokumentów, z których każdy może wskazywać 1–N dokumentów.
Każdy backend pamięci masowej udostępnia poszczególne pliki i katalogi, odwołując się do nich za pomocą unikalnego COLUMN_DOCUMENT_ID. Identyfikatory dokumentów są unikalne i nie zmieniają się po wydaniu, ponieważ są używane do trwałych przyznań URI po ponownym uruchomieniu urządzenia.
Dokumenty mogą być plikami z określonym typem MIME lub katalogami zawierającymi dodatkowe dokumenty z typem MIME MIME_TYPE_DIR.
Każdy dokument może mieć różne możliwości, jak opisano w sekcji COLUMN_FLAGS. na przykład FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE i FLAG_SUPPORTS_THUMBNAIL. Ten sam COLUMN_DOCUMENT_ID może występować w kilku katalogach.

Kontrola przepływu

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

Na rysunku 2 widać, jak aplikacja do zdjęć może używać SAF do uzyskiwania dostępu do zapisanych danych:

**Rysunek 2.** Schemat dostępu do pamięci.

Uwaga:

W tym przypadku dostawcy i klienci nie wchodzą w bezpośrednią interakcję. Klient prosi o pozwolenie na interakcję z plikami, czyli ich odczytywanie, edytowanie, tworzenie i usuwanie.
Interakcja rozpoczyna się, gdy aplikacja (w tym przykładzie aplikacja do zdjęć) wywoła intencję ACTION_OPEN_DOCUMENT lub ACTION_CREATE_DOCUMENT. Intencja może zawierać filtry, które pozwolą na dalsze doprecyzowanie kryteriów, np. „daj mi wszystkie otwieralne pliki, które mają typ MIME 'image'”.
Gdy intencja zostanie uruchomiona, selektor systemu przechodzi do każdego zarejestrowanego dostawcy i wyświetla użytkownikowi pasujące katalogi źródeł treści.
Selektor udostępnia użytkownikom standardowy interfejs dostępu do dokumentów, nawet gdy dostawcy dokumentów są bardzo różni. Na przykład rysunek 2 przedstawia dostawcę Dysku Google, dostawcę USB i dostawcę chmury.

Na rysunku 3 użytkownik wybiera folder Pobrane w selektorze otwartym podczas wyszukiwania obrazów. Selektor pokazuje też wszystkie korzenie dostępne dla aplikacji klienta.

Wybór folderu w selektorze systemowym. — **Rysunek 3.** Selektor pokazujący folder Pobrane jako wybraną lokalizację wyszukiwania.

Gdy użytkownik wybierze folder Pobrane, wyświetlą się obrazy. Rysunek 4 przedstawia wynik tego procesu. Użytkownik może teraz wchodzić w interakcje z obrazami w sposób obsługiwany przez dostawcę i aplikację klienta.

**Rysunek 4.** Obrazy przechowywane w folderze Pobrane, jak widać w selektorze systemowym.

Tworzenie aplikacji klienckiej

W przypadku Androida 4.3 lub starszego, jeśli chcesz, aby Twoja aplikacja pobierała pliki z innej aplikacji, musi wywołać intencję, taką jak ACTION_PICK lub ACTION_GET_CONTENT. Następnie użytkownik wybiera jedną aplikację, z której chce wybrać plik. Wybrana aplikacja musi zawierać interfejs, który umożliwia przeglądanie dostępnych plików i wybieranie ich.

W Androidzie 4.4 (interfejs API 19) lub nowszym możesz dodatkowo użyć intencji ACTION_OPEN_DOCUMENT, która wyświetla kontrolowany przez system interfejs selektora, umożliwiający użytkownikowi przeglądanie wszystkich plików udostępnionych przez inne aplikacje. W ramach tego jednego interfejsu użytkownik może wybrać plik z dowolnej obsługiwanej aplikacji.

W Androidzie 5.0 (poziom interfejsu API 21) lub nowszym możesz też użyć inencji ACTION_OPEN_DOCUMENT_TREE, która pozwala użytkownikowi wybrać katalog, do którego ma uzyskać dostęp aplikacja kliencka.

Uwaga: ACTION_OPEN_DOCUMENT nie zastępuje ACTION_GET_CONTENT. Wybór zależy od potrzeb aplikacji:

Użyj ACTION_GET_CONTENT, jeśli chcesz, aby aplikacja odczytywała lub importowała dane. W tym przypadku aplikacja importuje kopię danych, takich jak plik obrazu.
Użyj opcji ACTION_OPEN_DOCUMENT, jeśli chcesz, aby Twoja aplikacja miała długotrwały dostęp do dokumentów należących do dostawcy. Przykładem może być aplikacja do edycji zdjęć, która umożliwia użytkownikom edytowanie obrazów przechowywanych u dostawcy dokumentów.

Więcej informacji o obsługiwaniu przeglądania plików i katalogów za pomocą interfejsu selektora systemu znajdziesz w przewodniku Dostęp do dokumentów i innych plików.