Mengakses dokumen dan file lainnya dari penyimpanan bersama

Pada perangkat yang menjalankan Android 4.4 (Level API 19) dan yang lebih tinggi, aplikasi Anda dapat berinteraksi dengan penyedia dokumen, termasuk volume penyimpanan eksternal dan penyimpanan berbasis cloud, menggunakan Storage Access Framework. Framework ini memungkinkan pengguna berinteraksi dengan alat pilih sistem guna memilih penyedia dokumen serta memilih dokumen tertentu dan file lainnya untuk dibuat, dibuka, dan dimodifikasi aplikasi Anda.

Karena pengguna terlibat dalam pemilihan file atau direktori yang dapat diakses oleh aplikasi Anda, mekanisme ini tidak memerlukan izin sistem apa pun, serta privasi dan kontrol pengguna akan ditingkatkan. Selain itu, file ini, yang disimpan di luar direktori khusus aplikasi dan di luar penyimpanan media, akan tetap berada di perangkat setelah aplikasi Anda di-uninstal.

Penggunaan framework mencakup langkah-langkah berikut:

1. Aplikasi memanggil intent yang berisi tindakan terkait penyimpanan. Tindakan ini sesuai dengan kasus penggunaan tertentu yang disediakan oleh framework.
2. Pengguna akan melihat pemilih sistem, sehingga dapat menjelajahi penyedia dokumen dan memilih lokasi atau dokumen tempat tindakan terkait penyimpanan dilakukan.
3. Aplikasi mendapatkan akses baca dan tulis ke URI yang merepresentasikan lokasi atau dokumen yang dipilih pengguna. Dengan menggunakan URI ini, aplikasi dapat melakukan operasi pada lokasi yang dipilih.

Untuk mendukung akses file media di perangkat yang menjalankan Android 9 (Level API 28) atau yang lebih rendah, deklarasikan izin READ_EXTERNAL_STORAGE dan setel maxSdkVersion ke 28.

Panduan ini menjelaskan berbagai kasus penggunaan yang didukung oleh framework untuk bekerja dengan file dan dokumen lainnya. Panduan ini juga menjelaskan cara melakukan operasi pada lokasi yang dipilih pengguna.

Kasus penggunaan untuk mengakses dokumen dan file lainnya

Storage Access Framework mendukung kasus penggunaan berikut untuk mengakses file dan dokumen lainnya.

Membuat file baru

Tindakan intent ACTION_CREATE_DOCUMENT memungkinkan pengguna menyimpan file di lokasi tertentu.

Membuka dokumen atau file

Tindakan intent ACTION_OPEN_DOCUMENT memungkinkan pengguna memilih dokumen atau file tertentu yang akan dibuka.

Memberikan akses ke konten direktori

Tindakan intent ACTION_OPEN_DOCUMENT_TREE, yang tersedia di Android 5.0 (Level API 21) dan yang lebih tinggi, memungkinkan pengguna memilih direktori tertentu, yang memberikan aplikasi Anda akses ke semua file dan subdirektori dalam direktori tersebut.

Bagian berikut memberikan panduan tentang cara mengonfigurasi setiap kasus penggunaan.

Membuat file baru

Gunakan tindakan intent ACTION_CREATE_DOCUMENT untuk memuat pemilih file sistem dan memungkinkan pengguna memilih lokasi untuk menulis isi file. Proses ini mirip dengan yang digunakan dalam dialog "simpan sebagai" yang digunakan oleh sistem operasi lain.

Saat mengonfigurasi intent, tentukan nama file dan jenis MIME, serta tentukan URI file atau direktori secara opsional yang akan ditampilkan oleh alat pilih file saat file pertama kali dimuat menggunakan intent tambahan EXTRA_INITIAL_URI.

Cuplikan kode berikut menunjukkan cara membuat dan memanggil intent untuk membuat file:

// Request code for creating a PDF document.
const val CREATE_FILE = 1

private fun createFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_CREATE_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"
        putExtra(Intent.EXTRA_TITLE, "invoice.pdf")

        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker before your app creates the document.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }
    startActivityForResult(intent, CREATE_FILE)
}

// Request code for creating a PDF document.
private static final int CREATE_FILE = 1;

private void createFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");
    intent.putExtra(Intent.EXTRA_TITLE, "invoice.pdf");

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when your app creates the document.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, CREATE_FILE);
}

Membuka file

Aplikasi Anda mungkin menggunakan dokumen sebagai unit penyimpanan tempat pengguna memasukkan data yang mungkin ingin mereka bagikan kepada rekan atau impor ke dokumen lain. Beberapa contohnya antara lain pengguna yang membuka dokumen produktivitas atau membuka buku yang disimpan sebagai file EPUB.

Dalam kasus ini, izinkan pengguna memilih file yang akan dibuka dengan memanggil intent ACTION_OPEN_DOCUMENT, yang membuka aplikasi alat pilih file sistem. Untuk hanya menampilkan jenis file yang didukung aplikasi Anda, tentukan jenis MIME. Selain itu, Anda juga dapat secara opsional menentukan URI file yang akan ditampilkan oleh alat pilih file saat file tersebut pertama kali dimuat menggunakan intent tambahan EXTRA_INITIAL_URI.

Cuplikan kode berikut menunjukkan cara membuat dan memanggil intent untuk membuka dokumen PDF:

// Request code for selecting a PDF document.
const val PICK_PDF_FILE = 2

fun openFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"

        // Optionally, specify a URI for the file that should appear in the
        // system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent,