Seletor de fotos

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.
Figura 1. O seletor de fotos oferece uma IU intuitiva para compartilhar fotos com o app.

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:

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:

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.
    }
}