
O seletor de fotos tem uma interface em que é possível navegar e fazer pesquisas. Nela, o usuário tem acesso à biblioteca de mídia, organizada da mais recente para a mais antiga. Conforme mostrado no codelab de práticas recomendadas de privacidade, o seletor de fotos oferece uma maneira segura e integrada para os usuários concederem ao app acesso apenas aos vídeos e imagens selecionados, e não à biblioteca de mídia inteira.
A ferramenta é atualizada automaticamente, oferecendo mais funcionalidades aos usuários do app ao longo do tempo, sem exigir nenhuma mudança de código.
O seletor de fotos está disponível em dispositivos que atendem aos seguintes critérios:
- Executam o Android 11 (nível 30 da API) ou mais recente.
- Recebem mudanças nos componentes modulares do sistema pelas atualizações do sistema do Google.
Usar contratos de atividade do Jetpack
Para simplificar a integração do seletor de fotos, inclua a versão 1.6.1 ou mais recente da
biblioteca androidx.activity
.
Use estes contratos de resultados da atividade para iniciar o seletor de fotos:
PickVisualMedia
, para selecionar um único vídeo ou imagem.PickMultipleVisualMedia
, para selecionar vários vídeos ou imagens.
Se o seletor de fotos não estiver disponível em um dispositivo, a biblioteca
vai invocar a
ação da intent
ACTION_OPEN_DOCUMENT
de forma automática. Essa intent oferece suporte a dispositivos que executam o Android 4.4
(nível 19 da API) ou versões mais recentes. É possível verificar se o seletor de fotos está disponível
em um determinado dispositivo chamando
isPhotoPickerAvailable()
.
Selecionar um único item de mídia
Para selecionar um único item de mídia, use o contrato de resultado da atividade
PickVisualMedia
, conforme mostrado no snippet de código abaixo:
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());
Selecionar vários itens de mídia
Para selecionar vários itens de mídia, defina um número máximo de arquivos de mídia selecionáveis, conforme mostrado no snippet de código a seguir.
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());
A plataforma limita o número máximo de arquivos que você pode pedir ao usuário
para selecionar no seletor de fotos. Para acessar esse limite, chame
getPickImagesMaxLimit()
.
Nos dispositivos sem suporte ao seletor de fotos, esse limite é ignorado.
Manter o acesso ao arquivo de mídia
Por padrão, o sistema concede ao app acesso a arquivos de mídia até que o dispositivo seja
reiniciado ou até que o app seja interrompido. Se o app executar um trabalho de longa duração, como
o upload de um arquivo grande em segundo plano, talvez seja necessário que esse acesso persista por
um período mais longo. Para fazer isso, chame o
método
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);
Conferir se o seletor de fotos está disponível
A seção abaixo descreve como usar uma biblioteca de framework para verificar se o seletor de fotos está disponível em um determinado dispositivo. Esse fluxo de trabalho permite que você personalize o comportamento de inicialização do seletor de fotos e não dependa da Biblioteca de Suporte.
Para usar a versão do seletor de fotos fornecida pelo framework, adicione esta lógica ao app:
Kotlin
import android.os.ext.SdkExtensions.getExtensionVersion private 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 } } fun handlePhotoPickerLaunch() { if (isPhotoPickerAvailable()) { // To launch the system photo picker, invoke an intent that includes the // ACTION_PICK_IMAGES action. Consider adding support for the // EXTRA_PICK_IMAGES_MAX intent extra. } else { // Consider implementing fallback functionality so that users can still // select images and videos. } }
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; } } public void launchPhotoPicker() { if (isPhotoPickerAvailable()) { // To launch the system photo picker, invoke an intent that includes the // ACTION_PICK_IMAGES action. Consider adding support for the // EXTRA_PICK_IMAGES_MAX intent extra. } else { // Consider implementing fallback functionality so that users can still // select images and videos. } }