Pemilih foto

Gambar 1. Pemilih foto menyediakan UI yang intuitif untuk berbagi foto dengan aplikasi.

Pemilih foto menyediakan antarmuka yang dapat ditelusuri yang menyajikan library media kepada pengguna, yang diurutkan berdasarkan tanggal dari yang terbaru hingga terlama. Seperti yang ditunjukkan dalam codelab praktik terbaik privasi, pemilih foto menyediakan cara bawaan yang aman bagi pengguna untuk memberikan aplikasi Anda akses ke hanya gambar dan video yang dipilih, bukan seluruh koleksi media mereka.

Pengguna yang memiliki penyedia media cloud yang memenuhi syarat di perangkat mereka juga dapat memilih dari foto dan video yang disimpan dari jarak jauh. Pelajari lebih lanjut penyedia media cloud.

Alat ini otomatis diupdate, menawarkan fungsi yang diperluas kepada pengguna aplikasi Anda dari waktu ke waktu tanpa memerlukan perubahan kode apa pun.

Menggunakan kontrak Aktivitas Jetpack

Untuk menyederhanakan integrasi pemilih foto, sertakan library androidx.activity versi 1.7.0 atau yang lebih baru.

Gunakan kontrak hasil aktivitas berikut untuk meluncurkan pemilih foto:

• PickVisualMedia, untuk memilih satu gambar atau video.
• PickMultipleVisualMedia, untuk memilih beberapa gambar atau video.

Jika pemilih foto tidak tersedia di perangkat, 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:

View

// 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 let the user choose from.

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

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

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

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

Penayangan

// 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 let the user choose from.

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

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

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

// Launch the photo picker and let the user 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());

Compose

// Registers a photo picker activity launcher in single-select mode.
val pickMedia = rememberLauncherForActivityResult(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 let the user choose from.

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

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

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

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

Catatan: Saat menggunakan PickVisualMedia, pemilih foto akan terbuka dalam mode setengah layar.

Memilih beberapa item media

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

View

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user 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 let the user 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))

Penayangan

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user select up to 5 media files.
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 let the user 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());

Compose

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user select up to 5 media files.
val pickMultipleMedia =
        rememberLauncherForActivityResult(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 let the user 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))

Platform ini membatasi jumlah maksimum file yang dapat Anda minta untuk dipilih pengguna dalam pemilih foto. Untuk mengakses batas ini, panggil getPickImagesMaxLimit(). Pada perangkat yang tidak mendukung pemilih foto, batas ini akan diabaikan.

Catatan: Jika pemilih foto tidak tersedia dan support library memanggil tindakan intent ACTION_OPEN_DOCUMENT, sistem akan mengabaikan jumlah maksimum yang ditentukan untuk file media yang dapat dipilih.

Ketersediaan perangkat

Pemilih foto tersedia di perangkat yang memenuhi kriteria berikut:

• Menjalankan Android 11 (API level 30) atau yang lebih baru
• Menerima perubahan pada Komponen Sistem Modular melalui Update Sistem Google

Perangkat lama yang menjalankan Android 4.4 (API level 19) hingga Android 10 (API level 29) dan perangkat Android Go yang menjalankan Android 11 atau 12 yang mendukung layanan Google Play dapat menginstal pemilih foto versi backport. Untuk mengaktifkan penginstalan otomatis modul pemilih foto yang di-backport melalui layanan Google Play, tambahkan entri berikut ke tag <application> dalam file manifes aplikasi:

<!-- Trigger Google Play services to install the backported photo picker module. -->
<service android:name="com.google.android.gms.metadata.ModuleDependencies"
         android:enabled="false"
         android:exported="false"
         tools:ignore="MissingClass">
    <intent-filter>
        <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
    </intent-filter>
    <meta-data android:name="photopicker_activity:0:required" android:value="" />
</service>

Mempertahankan akses file media

Secara default, sistem memberi aplikasi Anda akses ke file media hingga perangkat dimulai ulang atau hingga aplikasi berhenti. Jika aplikasi Anda melakukan pekerjaan yang berjalan lama, seperti mengupload file besar di latar belakang, Anda mungkin memerlukan akses ini untuk dipertahankan dalam jangka waktu yang lebih lama. Untuk melakukannya, panggil metode takePersistableUriPermission():

Kotlin

val flag = Intent.FLAG_GRANT_READ_URI_PERMISSION
context.contentResolver.takePersistableUriPermission(uri, flag)

Java

int flag = Intent.FLAG_GRANT_READ_URI_PERMISSION;
context.contentResolver.takePersistableUriPermission(uri, flag);

Menangani video HDR dengan transcoding

Android 13 (API 33) memperkenalkan kemampuan untuk merekam video Rentang Dinamis Tinggi (HDR). Meskipun HDR menawarkan pengalaman visual yang lebih kaya, beberapa aplikasi lama mungkin tidak dilengkapi untuk menangani format yang lebih baru ini, sehingga menyebabkan masalah seperti rendering warna yang tidak alami selama pemutaran (seperti wajah yang berwarna hijau). Untuk mengatasi kesenjangan kompatibilitas ini, pemilih foto menawarkan fitur transcoding yang dapat mengonversi video HDR secara otomatis ke format Standard Dynamic Range (SDR) sebelum menyediakannya untuk aplikasi yang meminta.

Tujuan utama transkode pemilihan foto adalah untuk memastikan pengalaman media yang konsisten dan akurat secara visual di berbagai aplikasi, bahkan aplikasi yang belum memiliki dukungan HDR eksplisit. Dengan mentranskode video HDR ke SDR, pemilih foto bertujuan untuk meningkatkan kompatibilitas aplikasi dan memberikan pengalaman pengguna yang lancar.

Cara kerja transkode pemilihan foto

Transcoding HDR pemilih foto tidak diaktifkan secara default. Untuk mengaktifkan fitur ini, aplikasi Anda harus secara eksplisit menyatakan kemampuan penanganan format media saat meluncurkan pemilih foto.

Aplikasi Anda menyediakan kemampuan pemrosesan medianya ke pemilih foto. Hal ini dilakukan saat meluncurkan pemilih foto menggunakan library Aktivitas AndroidX dengan menambahkan mediaCapabilities ke PickVisualMediaRequest.Builder. API baru, setMediaCapabilitiesForTranscoding(capabilities: MediaCapabilities?), telah ditambahkan ke PickVisualMediaRequest.Builder untuk memfasilitasi hal ini.

Anda dapat mengontrol perilaku transkode HDR menggunakan class MediaCapabilities. Berikan objek MediaCapabilities yang menentukan secara persis jenis HDR yang didukung aplikasi Anda (misalnya, TYPE_HLG10, TYPE_HDR10, TYPE_HDR10_PLUS, TYPE_DOLBY_VISION).

Untuk menonaktifkan transcoding sepenuhnya, teruskan null untuk MediaCapabilities. Semua jenis HDR yang tidak tercantum secara eksplisit dalam kemampuan yang Anda berikan akan dianggap tidak didukung. API ini didukung di Android 13 (level API 33) dan yang lebih tinggi serta diberi anotasi dengan @RequiresApi(Build.VERSION_CODES.TIRAMISU).

import androidx.activity.result.PickVisualMediaRequest
import androidx.activity.result.contract.ActivityResultContracts.PickVisualMedia
import androidx.annotation.RequiresApi
import android.os.Build
import android.util.Log
import android.provider.MediaStore

// Registers a photo picker activity launcher.
val pickMedia = registerForActivityResult(PickVisualMedia()) { uri ->
    // Callback invoked after media selected or picker activity closed.
    if (uri != null) {
        Log.d("photo picker", "Selected URI: $uri")
    } else {
        Log.d("photo picker", "No media selected")
    }
}

@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun launchPhotoPickerWithTranscodingSupport() {
    val mediaCapabilities = MediaCapabilities.Builder()
        .addSupportedHdrType(MediaCapabilities.HdrType.TYPE_HLG10)
        .build()

    // Launch the photo picker and let the user choose only videos with
    // transcoding enabled.
    pickMedia.launch(PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.VideoOnly)
        .setMediaCapabilitiesForTranscoding(mediaCapabilities)
        .build())
}

Transcoding oleh pemilih foto didasarkan pada kemampuan media aplikasi dan video yang dipilih. URI ke video yang di-transcoding akan ditampilkan jika transcoding dilakukan.

Pertimbangan penting untuk transcoding HDR

• Performa dan penyimpanan: Transkode memerlukan waktu pemrosesan dan membuat file baru, yang menggunakan ruang penyimpanan.
• Batas durasi video: Untuk menyeimbangkan pengalaman pengguna dan batasan penyimpanan, ada batas durasi video 1 menit.
• Pengelolaan file yang di-cache: File yang di-transcode dan di-cache akan dihapus secara berkala selama pemeliharaan saat perangkat tidak digunakan untuk mencegah penggunaan penyimpanan yang berlebihan.
• Ketersediaan perangkat: Transkode pemilih foto didukung di Android 13 (level API 33) dan yang lebih baru.
• Integrasi aktivitas AndroidX: Pastikan Anda menggunakan library AndroidX Activity versi 1.11.0-alpha01 atau rilis alpha/beta/RC/stabil yang lebih baru, karena versi ini menyertakan API setMediaCapabilitiesForTranscoding yang diperlukan.