![A caixa de diálogo do seletor de fotos aparece com arquivos de mídia do dispositivo. Selecione uma foto para compartilhar com o app.](https://developer.android.com/static/images/training/data-storage/photo-picker-multiselect.gif?authuser=0000&hl=pt)
O seletor de fotos fornece uma interface navegável que apresenta as usuário com a biblioteca de mídia, classificada por data 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.
Os usuários que têm provedores de mídia em nuvem qualificados no dispositivo também podem selecionar fotos e vídeos armazenados remotamente. Saiba mais sobre provedores de mídia em nuvem.
A ferramenta é atualizada automaticamente, oferecendo mais funcionalidades aos usuários do app ao longo do tempo, sem exigir nenhuma mudança de código.
Usar contratos de atividade do Jetpack
Para simplificar a integração do seletor de fotos, inclua a versão 1.7.0 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 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)))
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 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());
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 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))
Java
// 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());
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.
Disponibilidade de dispositivos
O seletor de fotos está disponível em dispositivos que atendem a estes 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.
É possível instalar uma versão de backport do seletor de fotos em dispositivos mais antigos com o Android 4.4 (nível 19 da API) ao Android 10 (nível 29 da API),
e também em dispositivos Android Go com o Android 11 ou 12 com suporte ao
Google Play Services. Para
ativar a instalação automática do módulo do seletor de fotos com backport pelo
Google Play Services, adicione a entrada abaixo à tag <application>
no
arquivo de manifesto do app:
<!-- 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>
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);