Membuka file menggunakan Storage Access Framework

Android 4.4 (API level 19) memperkenalkan Storage Access Framework (SAF). SAF memungkinkan pengguna menjelajahi dan membuka dokumen, gambar, dan file lainnya di semua penyedia penyimpanan dokumen pilihan mereka. UI standar yang mudah digunakan memungkinkan pengguna menjelajahi file dan mengakses file terbaru secara konsisten di berbagai 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 Anda memiliki akses jangka panjang dan persisten ke dokumen yang dimiliki oleh penyedia dokumen. Melalui akses ini, pengguna dapat menambah, mengedit, menyimpan, dan menghapus file di penyedia.
  • Mendukung beberapa akun pengguna dan root sementara seperti penyedia penyimpanan USB, yang hanya muncul jika drive dicolokkan.

Ringkasan

SAF berpusat di seputar penyedia konten yang merupakan subclass dari class DocumentsProvider. Dalam penyedia dokumen, data disusun secara terstruktur sebagai hierarki file biasa:

model data

Gambar 1. Model data penyedia dokumen. Root menunjuk ke satu dokumen, yang kemudian memulai proses fan-out pohon.

Perhatikan hal berikut:

  • Setiap penyedia dokumen melaporkan satu atau beberapa root, yang merupakan titik awal penjelajahan pohon dokumen. Setiap root memiliki COLUMN_ROOT_ID yang unik, dan mengarah ke dokumen (direktori) yang mewakili konten di bawah root tersebut. Root sengaja dibuat dinamis untuk mendukung kasus penggunaan seperti beberapa akun, perangkat penyimpanan USB sementara, 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 dikeluarkan, karena digunakan untuk pemberian URI persisten saat 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 di beberapa direktori.

Alur kontrol

Model data penyedia dokumen didasarkan pada hierarki file biasa. Namun, Anda dapat menyimpan data secara fisik sesuka Anda, selama Anda dapat 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:

aplikasi

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, artinya membaca, mengedit, membuat, atau menghapus file.
  • Interaksi dimulai saat aplikasi, dalam contoh ini adalah aplikasi foto, mengaktifkan intent ACTION_OPEN_DOCUMENT atau ACTION_CREATE_DOCUMENT. Intent tersebut dapat menyertakan 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 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 terbuka dalam penelusuran gambar. Pemilih juga menampilkan semua root yang tersedia untuk aplikasi klien.

Screenshot pilihan folder di alat pilih sistem

Gambar 3. Pemilih 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 bisa berinteraksi dengan gambar dengan cara yang didukung oleh penyedia dan aplikasi klien.

Screenshot folder Download

Gambar 4. Gambar yang disimpan di folder Download, seperti yang dilihat 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. Kemudian, pengguna memilih satu aplikasi untuk memilih file. Aplikasi yang dipilih harus menyediakan antarmuka pengguna bagi pengguna untuk menjelajahi dan memilih dari file yang tersedia.

Di 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 oleh aplikasi lain. Dari satu UI ini, pengguna dapat memilih file dari aplikasi apa pun yang didukung.

Di 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 jangka panjang dan persisten ke dokumen yang dimiliki oleh 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:

Contoh

Video