Halaman ini diterjemahkan oleh Cloud Translation API.

Membuka file menggunakan Storage Access Framework
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.
Aplikasi klien: aplikasi kustom yang memanggil tindakan intent ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT, dan ACTION_OPEN_DOCUMENT_TREE, serta menerima file yang ditampilkan oleh penyedia dokumen.
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.
Setiap dokumen bisa memiliki kemampuan yang berbeda, seperti yang dijelaskan COLUMN_FLAGS. Misalnya, FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE, dan FLAG_SUPPORTS_THUMBNAIL. COLUMN_DOCUMENT_ID yang sama dapat disertakan dalam beberapa direktori.

Alur kontrol

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.

Pilihan folder di alat pilih sistem. — **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.