Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Android 4.4 (API level 19) memperkenalkan Storage Access Framework (SAF). SAF
memungkinkan pengguna menjelajahi dan membuka dokumen, gambar, serta file lain
di semua penyedia penyimpanan dokumen pilihannya. UI standar yang mudah digunakan
memungkinkan pengguna menjelajahi file dan mengakses file terbaru secara konsisten di semua aplikasi dan penyedia.
Layanan penyimpanan cloud atau lokal dapat dilibatkan dalam ekosistem ini dengan menerapkan
DocumentsProvider yang merangkum layanannya. Aplikasi
klien yang memerlukan akses ke dokumen penyedia dapat berintegrasi dengan SAF dengan beberapa
baris kode.
SAF mencakup:
Penyedia dokumen: penyedia konten yang memungkinkan
layanan penyimpanan, seperti Google Drive, menampilkan file yang dikelolanya. Penyedia dokumen
diterapkan sebagai subclass dari class DocumentsProvider.
Skema penyedia dokumen didasarkan pada hierarki file biasa,
meskipun Anda yang menentukan bagaimana penyedia dokumen menyimpan data secara fisik.
Platform Android menyertakan beberapa penyedia dokumen bawaan, seperti
Download, Gambar, dan Video.
Alat pilih: UI sistem yang memungkinkan pengguna mengakses dokumen dari semua
penyedia dokumen yang memenuhi kriteria penelusuran aplikasi klien.
SAF menawarkan fitur berikut:
Memungkinkan pengguna menjelajahi konten dari semua penyedia dokumen, bukan hanya satu aplikasi.
Memungkinkan aplikasi memiliki akses tetap jangka panjang ke
dokumen yang dimiliki penyedia dokumen. Melalui akses ini, pengguna dapat menambahkan, mengedit,
menyimpan, dan menghapus file pada penyedia.
Mendukung banyak akun pengguna dan root transien seperti penyedia penyimpanan USB,
yang hanya muncul jika drive terpasang.
Ringkasan
SAF berpusat di seputar penyedia konten yang merupakan
subclass dari class DocumentsProvider. Dalam penyedia dokumen, data disusun secara terstruktur sebagai hierarki file biasa:
Gambar 1. Model data penyedia dokumen. Root menunjuk ke satu dokumen, yang kemudian memulai fan-out pohon.
Perhatikan hal berikut:
Setiap penyedia dokumen melaporkan satu atau beberapa
root, yang merupakan titik awal penjelajahan hierarki dokumen.
Setiap root memiliki COLUMN_ROOT_ID yang unik,
dan itu menunjuk ke dokumen (direktori) yang
mewakili konten di bawah root tersebut.
Root sengaja dibuat dinamis untuk mendukung kasus penggunaan seperti banyak akun,
perangkat penyimpanan USB transien, atau login dan logout pengguna.
Di bawah setiap root terdapat satu dokumen. Dokumen itu menunjuk ke 1 hingga N dokumen,
yang masing-masing pada gilirannya bisa menunjuk ke 1 hingga N dokumen.
Setiap backend penyimpanan memunculkan
masing-masing file dan direktori dengan merujuknya melalui
COLUMN_DOCUMENT_ID yang unik.
ID dokumen bersifat unik dan tidak berubah setelah dibuat, karena ID ini digunakan untuk pemberian URI persisten
pada semua tindakan mulai ulang perangkat.
Dokumen dapat berupa file yang dapat dibuka, dengan jenis MIME tertentu, atau
direktori yang berisi dokumen tambahan, dengan
jenis MIME MIME_TYPE_DIR.
Model data penyedia dokumen didasarkan pada hierarki
file biasa. Namun, Anda dapat secara fisik menyimpan data dengan cara apa pun yang diinginkan, selama
Anda bisa mengaksesnya menggunakan API
DocumentsProvider. Misalnya, Anda dapat menggunakan penyimpanan cloud berbasis tag untuk data Anda.
Gambar 2 menunjukkan cara aplikasi foto bisa menggunakan SAF
untuk mengakses data tersimpan:
Gambar 2. Alur Storage Access Framework.
Perhatikan hal berikut:
Di SAF, penyedia dan klien tidak berinteraksi
secara langsung. Klien meminta izin untuk berinteraksi
dengan file, yang berarti membaca, mengedit, membuat, atau menghapus file.
Interaksi dimulai saat aplikasi, dalam contoh ini aplikasi foto, mengaktifkan
intent ACTION_OPEN_DOCUMENT atau ACTION_CREATE_DOCUMENT.
Intent ini dapat mencakup filter
untuk lebih menyaring kriteria, seperti "beri saya semua file yang dapat dibuka
yang memiliki jenis MIME 'gambar'".
Setelah intent diaktifkan, alat pilih sistem akan mengunjungi setiap penyedia yang terdaftar
dan menunjukkan root konten pencocokan kepada pengguna.
Alat pilih ini memberi pengguna antarmuka standar untuk mengakses dokumen, meskipun
penyedia dokumen yang mendasarinya sangat berbeda. Misalnya, gambar 2
menunjukkan penyedia Google Drive, penyedia USB, dan penyedia cloud.
Pada Gambar 3, pengguna memilih folder Download dari pemilih yang dibuka dalam penelusuran
gambar. Pemilih juga menampilkan semua root yang tersedia untuk aplikasi klien.
Gambar 3. Alat pilih yang menampilkan folder Download yang dipilih sebagai lokasi penelusuran.
Setelah pengguna memilih folder Download, gambar akan ditampilkan. Gambar 4
menunjukkan hasil proses ini. Pengguna kini dapat berinteraksi dengan gambar
melalui cara yang didukung penyedia dan aplikasi klien.
Gambar 4. Gambar yang disimpan di folder Download, seperti yang terlihat di alat pilih sistem.
Menulis aplikasi klien
Pada Android 4.3 dan yang lebih rendah, jika Anda ingin aplikasi mengambil file dari aplikasi
lain, aplikasi tersebut harus memanggil intent seperti ACTION_PICK
atau ACTION_GET_CONTENT. Pengguna kemudian memilih
satu aplikasi untuk memilih file. Aplikasi yang dipilih harus menyediakan antarmuka
agar pengguna dapat menjelajahi dan memilih dari file yang tersedia.
Pada Android 4.4 (API level 19) dan yang lebih tinggi, Anda memiliki opsi tambahan untuk menggunakan
intent ACTION_OPEN_DOCUMENT,
yang menampilkan UI alat pilih yang dikontrol sistem yang memungkinkan pengguna
menjelajahi semua file yang disediakan aplikasi lain. Dari satu UI ini, pengguna dapat
memilih file dari aplikasi apa pun yang didukung.
Pada Android 5.0 (API level 21) dan yang lebih tinggi, Anda juga dapat menggunakan
intent ACTION_OPEN_DOCUMENT_TREE, yang memungkinkan pengguna memilih direktori untuk diakses
aplikasi klien.
Catatan: ACTION_OPEN_DOCUMENT bukan pengganti ACTION_GET_CONTENT.
Yang Anda gunakan bergantung pada kebutuhan aplikasi Anda:
Gunakan ACTION_GET_CONTENT jika Anda ingin aplikasi
membaca atau mengimpor data. Dengan pendekatan ini, aplikasi akan mengimpor salinan data,
seperti file gambar.
Gunakan ACTION_OPEN_DOCUMENT jika Anda ingin
aplikasi memiliki akses tetap jangka panjang ke dokumen yang dimiliki penyedia
dokumen. Contohnya adalah aplikasi pengeditan foto yang memungkinkan pengguna mengedit
gambar yang disimpan dalam penyedia dokumen.
Untuk informasi selengkapnya tentang cara mendukung penjelajahan file dan direktori
menggunakan UI alat pilih sistem, lihat panduan tentang
mengakses dokumen dan
file lainnya.
Referensi lainnya
Untuk informasi selengkapnya tentang penyedia dokumen, manfaatkan
referensi berikut:
Konten dan contoh kode di halaman ini tunduk kepada lisensi yang dijelaskan dalam Lisensi Konten. Java dan OpenJDK adalah merek dagang atau merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2025-07-27 UTC.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Informasi yang saya butuhkan tidak ada","missingTheInformationINeed","thumb-down"],["Terlalu rumit/langkahnya terlalu banyak","tooComplicatedTooManySteps","thumb-down"],["Sudah usang","outOfDate","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Masalah kode / contoh","samplesCodeIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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)"]]
