Pemilih foto

Dialog pemilih foto akan muncul dengan file media di perangkat Anda. Pilih foto untuk dibagikan ke aplikasi.
Gambar 1. Pemilih foto menyediakan UI yang intuitif untuk berbagi foto dengan aplikasi.

Pemilih foto menyediakan antarmuka yang dapat ditelusuri dan dapat dijelajahi yang menyajikan library media kepada pengguna, yang diurutkan berdasarkan tanggal dari yang terbaru hingga terlama. Alat ini memberikan cara bawaan yang aman bagi pengguna untuk memilih gambar dan video, tanpa perlu memberikan akses aplikasi Anda ke seluruh library media mereka.

Jika Anda mengizinkan sistem mengonfigurasi pemilih foto, alat ini akan tersedia di perangkat yang memenuhi kriteria berikut, kecuali untuk perangkat Android Go:

Selain itu, jika Anda mengizinkan sistem mengonfigurasi pemilih foto, alat ini akan otomatis diupdate yang menawarkan fungsi yang diperluas kepada pengguna aplikasi Anda dari waktu ke waktu tanpa memerlukan perubahan kode apa pun.

Atau, Anda dapat menyesuaikan pengalaman peluncuran pemilih foto di perangkat yang menjalankan Android 13 dan yang lebih baru.

Mengizinkan sistem mengonfigurasi pemilih foto

Support library pemilih foto memungkinkan Anda meluncurkan pemilih foto dari aplikasi menggunakan salah satu kontrak hasil aktivitas berikut:

Jika pemilih foto tidak tersedia di perangkat, support library akan otomatis memanggil tindakan intent ACTION_OPEN_DOCUMENT. Intent ini didukung pada perangkat yang menjalankan Android 4.4 (API level 19) atau yang lebih baru. Anda dapat memverifikasi apakah pemilih foto tersedia di perangkat tertentu dengan memanggil isPhotoPickerAvailable().

Memilih satu item media

Untuk memilih satu item media, gunakan kontrak hasil aktivitas PickVisualMedia, seperti yang ditunjukkan dalam cuplikan kode berikut:

Kotlin

// Registers a photo picker activity launcher in single-select mode.
val pickMedia = registerForActivityResult(PickVisualMedia()) { uri ->
    // Callback is invoked after the user selects a media item or closes the
    // photo picker.
    if (uri != null) {
        Log.d("PhotoPicker", "Selected URI: $uri")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// Include only one of the following calls to launch(), depending on the types
// of media that you want to allow the user to choose from.

// Launch the photo picker and allow the user to choose images and videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

// Launch the photo picker and allow the user to choose only images.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageOnly))

// Launch the photo picker and allow the user to choose only videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.VideoOnly))

// Launch the photo picker and allow the user to choose only images/videos of a
// specific MIME type, such as GIFs.
val mimeType = "image/gif"
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.SingleMimeType(mimeType)))

Java

// Registers a photo picker activity launcher in single-select mode.
ActivityResultLauncher<PickVisualMediaRequest> pickMedia =
        registerForActivityResult(new PickVisualMedia(), uri -> {
    // Callback is invoked after the user selects a media item or closes the
    // photo picker.
    if (uri != null) {
        Log.d("PhotoPicker", "Selected URI: " + uri);
    } else {
        Log.d("PhotoPicker", "No media selected");
    }
});

// Include only one of the following calls to launch(), depending on the types
// of media that you want to allow the user to choose from.

// Launch the photo picker and allow the user to choose images and videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

// Launch the photo picker and allow the user to choose only images.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageOnly.INSTANCE)
        .build());

// Launch the photo picker and allow the user to choose only videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.VideoOnly.INSTANCE)
        .build());

// Launch the photo picker and allow the user to choose only images/videos of a
// specific MIME type, such as GIFs.
String mimeType = "image/gif";
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(new PickVisualMedia.SingleMimeType(mimeType))
        .build());

Memilih beberapa item media

Untuk memilih beberapa item media, tetapkan jumlah maksimum file media yang dapat dipilih, seperti yang ditunjukkan dalam cuplikan kode berikut.

Kotlin

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app allows the user to select up to 5 media files.
val pickMultipleMedia =
        registerForActivityResult(PickMultipleVisualMedia(5)) { uris ->
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (uris.isNotEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: ${uris.size}")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// For this example, launch the photo picker and allow the user to choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

Java

// Registering Photo Picker activity launcher with multiple selects (5 max in this example)
ActivityResultLauncher<PickVisualMediaRequest> pickMultipleMedia =
        registerForActivityResult(new PickMultipleVisualMedia(5), uris -> {
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (!uris.isEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: " + uris.size());
    } else {
        Log.d("PhotoPicker", "No media selected");
    }
});

// For this example, launch the photo picker and allow the user to choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

Menyesuaikan pengalaman peluncuran pemilih foto

Bagian berikut menjelaskan cara menggunakan library framework untuk menyesuaikan intent yang akan meluncurkan pemilih foto.

Memeriksa apakah pemilih foto tersedia

Untuk memeriksa apakah pemilih foto tersedia di perangkat tertentu, sertakan logika yang ditunjukkan dalam cuplikan kode berikut:

Kotlin

import android.os.ext.SdkExtensions.getExtensionVersion

fun isPhotoPickerAvailable(): Boolean {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        true
    } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        getExtensionVersion(Build.VERSION_CODES.R) >= 2
    } else {
        false
    }
}

Java

import android.os.ext.SdkExtensions.getExtensionVersion;

private boolean isPhotoPickerAvailable() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        return true;
    } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        return getExtensionVersion(Build.VERSION_CODES.R) >= 2;
    } else
        return false;
    }
}

Menentukan batasan berbagi

Aplikasi dapat mendeklarasikan nilai untuk EXTRA_PICK_IMAGES_MAX, yang menunjukkan jumlah maksimum file media yang muncul di alat pilih foto saat ditampilkan kepada pengguna. Misalnya, jika Anda meminta pengguna memilih foto profil yang diperlukan untuk akunnya, tetapkan satu foto sebagai persyaratan berbagi maksimum.

Memilih satu item media

Untuk meluncurkan pemilih foto dalam mode pilihan tunggal, lakukan hal berikut:

Kotlin

// Launches photo picker in single-select mode.
// This means that the user can select one photo or video.
val intent = Intent(MediaStore.ACTION_PICK_IMAGES)
startActivityForResult(intent, PHOTO_PICKER_REQUEST_CODE)

Java

// Launches photo picker in single-select mode.
// This means that the user can select one photo or video.
Intent intent = new Intent(MediaStore.ACTION_PICK_IMAGES);
startActivityForResult(intent, PHOTO_PICKER_REQUEST_CODE);

Memilih beberapa item media

Jika kasus penggunaan aplikasi Anda mengharuskan pengguna memilih beberapa foto atau video, Anda dapat menentukan jumlah maksimum gambar yang akan muncul di pemilih foto menggunakan tambahan EXTRA_PICK_IMAGES_MAX, seperti yang ditunjukkan dalam kode cuplikan berikut:

Kotlin

// Launches photo picker in multi-select mode.
// This means that user can select multiple photos/videos, up to the limit
// specified by the app in the extra (10 in this example).
val maxNumPhotosAndVideos = 10
val intent = Intent(MediaStore.ACTION_PICK_IMAGES)
intent.putExtra(MediaStore.EXTRA_PICK_IMAGES_MAX, maxNumPhotosAndVideos)
startActivityForResult(intent, PHOTO_PICKER_MULTI_SELECT_REQUEST_CODE)

Java

// Launches photo picker in multi-select mode.
// This means that user can select multiple photos/videos, up to the limit
// specified by the app in the extra (10 in this example).
final int maxNumPhotosAndVideos = 10;
Intent intent = new Intent(MediaStore.ACTION_PICK_IMAGES);
intent.putExtra(MediaStore.EXTRA_PICK_IMAGES_MAX, maxNumPhotosAndVideos);
startActivityForResult(intent, PHOTO_PICKER_MULTI_SELECT_REQUEST_CODE);

Perhatikan bahwa ada batas platform pada jumlah terbesar yang dapat Anda tentukan sebagai jumlah file maksimum. Untuk mengakses batas ini, panggil getPickImagesMaxLimit().

Menangani hasil pemilih foto

Setelah pemilih foto diluncurkan, gunakan tindakan intent ACTION_PICK_IMAGES untuk menangani hasilnya. Pemilih menampilkan kumpulan URI:

Kotlin

// onActivityResult() handles callbacks from the photo picker.
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    super.onActivityResult(requestCode, resultCode, data)
    if (resultCode != Activity.RESULT_OK) {
        // Handle error
        return
    }
    when (requestCode) {
        REQUEST_PHOTO_PICKER_SINGLE_SELECT -> {
            // Get photo picker response for single select.
            val currentUri: Uri = data.data!!

            // Do stuff with the photo/video URI.
            return
    }
        REQUEST_PHOTO_PICKER_MULTI_SELECT -> {
            // Get photo picker response for multi select.
            var i = 0
            var currentUri: Uri

            while (i < data.clipData!!.itemCount) {
                currentUri = data.clipData!!.getItemAt(i).uri
                // Do stuff with each photo/video URI.
                i++
            }
            return
    }
}

Java

// onActivityResult() handles callbacks from the photo picker.
@Override
protected void onActivityResult(
    int requestCode, int resultCode, final Intent data) {

    if (resultCode != Activity.RESULT_OK) {
        // Handle error
        return;
    }

    switch(requestCode) {
        case REQUEST_PHOTO_PICKER_SINGLE_SELECT:
            // Get photo picker response for single select.
            Uri currentUri = data.getData();

            // Do stuff with the photo/video URI.
            return;
        case REQUEST_PHOTO_PICKER_MULTI_SELECT:
            // Get photo picker response for multi select
            for (int i = 0; i < data.getClipData().getItemCount(); i++) {
                Uri currentUri = data.getClipData().getItemAt(i).getUri();

                // Do stuff with each photo/video URI.
            }
            return;
    }
}

Secara default, pemilih foto akan menampilkan foto dan video. Anda juga dapat memfilter berdasarkan hanya foto atau hanya video dengan menyetel jenis MIME dalam metode setType(). Misalnya, untuk hanya menampilkan video di pemilih foto, teruskan video/* ke setType():

Kotlin

// Launches photo picker for videos only in single select mode.
val intent = Intent(MediaStore.ACTION_PICK_IMAGES)
intent.type = "video/*"
startActivityForResult(intent, PHOTO_PICKER_VIDEO_SINGLE_SELECT_REQUEST_CODE)

// Apps can also change the mimeType to allow users to select
// images only - intent.type = "images/*"

Java

// Launches photo picker for videos only in single select mode.
Intent intent = new Intent(MediaStore.ACTION_PICK_IMAGES);
intent.setType("video/*");
startActivityForResult(intent, PHOTO_PICKER_VIDEO_SINGLE_SELECT_REQUEST_CODE);

// Apps can also change the mimeType to allow users to select
// images only - intent.setType("image/*");
// or a specific mimeType - intent.setType("image/gif");