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.
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.
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.
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.
Dodatkowe materiały
Więcej informacji o dostawcach dokumentów znajdziesz w tych materiałach:
Treść strony i umieszczone na niej fragmenty kodu podlegają licencjom opisanym w Licencji na treści. Java i OpenJDK są znakami towarowymi lub zastrzeżonymi znakami towarowymi należącymi do firmy Oracle lub jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-07-27 UTC.
[[["Łatwo zrozumieć","easyToUnderstand","thumb-up"],["Rozwiązało to mój problem","solvedMyProblem","thumb-up"],["Inne","otherUp","thumb-up"]],[["Brak potrzebnych mi informacji","missingTheInformationINeed","thumb-down"],["Zbyt skomplikowane / zbyt wiele czynności do wykonania","tooComplicatedTooManySteps","thumb-down"],["Nieaktualne treści","outOfDate","thumb-down"],["Problem z tłumaczeniem","translationIssue","thumb-down"],["Problem z przykładami/kodem","samplesCodeIssue","thumb-down"],["Inne","otherDown","thumb-down"]],["Ostatnia aktualizacja: 2025-07-27 UTC."],[],[],null,["# Open files using the Storage Access Framework\n\nAndroid 4.4 (API level 19) introduces the Storage Access Framework (SAF). The SAF\nlets users browse and open documents, images, and other files\nacross all of their preferred document storage providers. A standard, easy-to-use UI\nlets users browse files and access recent files in a consistent way across apps and providers.\n\nCloud or local storage services can participate in this ecosystem by implementing a\n[DocumentsProvider](/reference/android/provider/DocumentsProvider) that encapsulates their services. Client\napps that need access to a provider's documents can integrate with the SAF with a few\nlines of code.\n\nThe SAF includes the following:\n\n- **Document provider:** a content provider that lets a storage service, such as Google Drive, reveal the files it manages. A document provider is implemented as a subclass of the [DocumentsProvider](/reference/android/provider/DocumentsProvider) class. The document-provider schema is based on a traditional file hierarchy, though how your document provider physically stores data is up to you. The Android platform includes several built-in document providers, such as Downloads, Images, and Videos.\n- **Client app:** a custom app that invokes the [ACTION_CREATE_DOCUMENT](/reference/android/content/Intent#ACTION_CREATE_DOCUMENT), [ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT), and [ACTION_OPEN_DOCUMENT_TREE](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE) intent actions and receives the files returned by document providers.\n- **Picker:** a system UI that lets users access documents from all document providers that satisfy the client app's search criteria.\n\nSAF offers the following features:\n\n- Lets users browse content from all document providers, not just a single app.\n- Makes it possible for your app to have long-term, persistent access to documents owned by a document provider. Through this access, users can add, edit, save, and delete files on the provider.\n- Supports multiple user accounts and transient roots such as USB storage providers, which only appear if the drive is plugged in.\n\nOverview\n--------\n\nThe SAF centers around a content provider that is a\nsubclass of the [DocumentsProvider](/reference/android/provider/DocumentsProvider) class. Within a document provider, data is\nstructured as a traditional file hierarchy:\n**Figure 1.** Document provider data model. A root points to a single document, which then starts the fan-out of the tree.\n\nNote the following:\n\n- Each document provider reports one or more *roots* , which are starting points into exploring a tree of documents. Each root has a unique [COLUMN_ROOT_ID](/reference/android/provider/DocumentsContract.Root#COLUMN_ROOT_ID), and it points to a document (a directory) representing the contents under that root. Roots are dynamic by design to support use cases like multiple accounts, transient USB storage devices, or user login and logout.\n- Under each root is a single document. That document points to 1 to *N* documents, each of which in turn can point to 1 to *N* documents.\n- Each storage backend surfaces individual files and directories by referencing them with a unique [COLUMN_DOCUMENT_ID](/reference/android/provider/DocumentsContract.Document#COLUMN_DOCUMENT_ID). Document IDs are unique and don't change once issued, since they are used for persistent URI grants across device reboots.\n- Documents can be either an openable file, with a specific MIME type, or a directory containing additional documents, with the [MIME_TYPE_DIR](/reference/android/provider/DocumentsContract.Document#MIME_TYPE_DIR) MIME type.\n- Each document can have different capabilities, as described by [COLUMN_FLAGS](/reference/android/provider/DocumentsContract.Document#COLUMN_FLAGS). For example, [FLAG_SUPPORTS_WRITE](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_WRITE), [FLAG_SUPPORTS_DELETE](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_DELETE), and [FLAG_SUPPORTS_THUMBNAIL](/reference/android/provider/DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL). The same `COLUMN_DOCUMENT_ID` can be included in multiple directories.\n\nControl flow\n------------\n\nThe document provider data model is based on a traditional\nfile hierarchy. However, you can physically store your data however you like, as\nlong as you can access it using the [DocumentsProvider](/reference/android/provider/DocumentsProvider)\nAPI. For example, you can use tag-based cloud storage for your data.\n\nFigure 2 shows how a photo app might use the SAF\nto access stored data:\n**Figure 2.** Storage Access Framework flow.\n\nNote the following:\n\n- In the SAF, providers and clients don't interact directly. A client requests permission to interact with files, meaning to read, edit, create, or delete files.\n- The interaction starts when an application, in this example a photo app, fires the intent [ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT) or [ACTION_CREATE_DOCUMENT](/reference/android/content/Intent#ACTION_CREATE_DOCUMENT). The intent can include filters to further refine the criteria, such as \"give me all openable files that have the 'image' MIME type.\"\n- Once the intent fires, the system picker goes to each registered provider and shows the user the matching content roots.\n- The picker gives users a standard interface for accessing documents, even when the underlying document providers are very different. For example, figure 2 shows a Google Drive provider, a USB provider, and a cloud provider.\n\nIn Figure 3, the user is selecting the Downloads folder from a picker opened in a search for\nimages. The picker also shows all of the roots available to the client app.\n**Figure 3.** Picker showing Downloads folder selected as a search location.\n\nAfter the user selects the Downloads folder, the images are displayed. Figure\n4 shows the result of this process. The user can now interact with the images\nin the ways that the provider and client app support.\n**Figure 4.** Images stored in the Downloads folder, as viewed in the system picker.\n\nWrite a client app\n------------------\n\nOn Android 4.3 and lower, if you want your app to retrieve a file from another\napp, it must invoke an intent such as [ACTION_PICK](/reference/android/content/Intent#ACTION_PICK)\nor [ACTION_GET_CONTENT](/reference/android/content/Intent#ACTION_GET_CONTENT). The user then selects\na single app from which to pick a file. The selected app must provide a user\ninterface for the user to browse and pick from the available files.\n\nOn Android 4.4 (API level 19) and higher, you have the additional option of using the\n[ACTION_OPEN_DOCUMENT](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT) intent,\nwhich displays a system-controlled picker UI that lets the user\nbrowse all files that other apps have made available. From this single UI, the\nuser can pick a file from any of the supported apps.\n\nOn Android 5.0 (API level 21) and higher, you can also use the\n[ACTION_OPEN_DOCUMENT_TREE](/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE)\nintent, which lets the user choose a directory for a client app to\naccess. \n**Note:** `ACTION_OPEN_DOCUMENT` isn't a replacement for `ACTION_GET_CONTENT`.\nThe one you use depends on the needs of your app:\n\n- Use `ACTION_GET_CONTENT` if you want your app to read or import data. With this approach, the app imports a copy of the data, such as an image file.\n- Use `ACTION_OPEN_DOCUMENT` if you want your app to have long-term, persistent access to documents owned by a document provider. An example is a photo-editing app that lets users edit images stored in a document provider.\n\nFor more information about how to support browsing for files and directories\nusing the system picker UI, see the guide about\n[accessing documents and\nother files](/training/data-storage/shared/documents-files).\n\nAdditional resources\n--------------------\n\nFor more information about document providers, take advantage of the\nfollowing resources:\n\n### Samples\n\n- [StorageProvider](https://github.com/android/storage-samples/tree/main/StorageProvider)\n\n### Videos\n\n- [DevBytes: Android 4.4 Storage Access Framework: Provider](http://www.youtube.com/watch?v=zxHVeXbK1P4)\n- [Virtual Files in the Storage Access Framework](https://www.youtube.com/watch?v=4h7yCZt231Y)"]]
