Sélecteur de photos

La boîte de dialogue du sélecteur de photos s'affiche avec les fichiers multimédias de votre appareil. Sélectionnez une photo à partager avec l'application.
Figure 1. Le sélecteur de photos offre une interface utilisateur intuitive permettant de partager des photos avec votre application.

Le sélecteur de photos fournit une interface de recherche consultable. Il présente à l'utilisateur sa bibliothèque multimédia, dans laquelle les éléments sont triés par date, du plus récent au plus ancien. Comme indiqué dans l'atelier de programmation sur les bonnes pratiques concernant la confidentialité, le sélecteur de photos offre aux utilisateurs un moyen intégré et sécurisé d'autoriser votre application à accéder uniquement aux images et vidéos sélectionnées, au lieu de l'intégralité de leur bibliothèque multimédia.

L'outil se met à jour automatiquement et offre ainsi des fonctionnalités étendues aux utilisateurs de votre application au fil du temps, sans avoir à modifier le code.

Le sélecteur de photos est disponible sur les appareils qui répondent aux critères suivants :

Utiliser des contrats d'activité Jetpack

Pour simplifier l'intégration du sélecteur de photos, incluez la version 1.6.1 ou ultérieure de la bibliothèque androidx.activity.

Utilisez les contrats de résultat d'activité suivants pour lancer le sélecteur de photos :

Si le sélecteur de photos n'est pas disponible sur un appareil, la bibliothèque appelle automatiquement l'action d'intent ACTION_OPEN_DOCUMENT à la place. Cet intent est compatible avec les appareils équipés d'Android 4.4 (niveau d'API 19) ou version ultérieure. Pour vérifier si le sélecteur de photos est disponible sur un appareil donné, appelez isPhotoPickerAvailable().

Sélectionner un seul élément multimédia

Pour sélectionner un seul élément multimédia, utilisez le contrat de résultat d'activité PickVisualMedia, comme indiqué dans l'extrait de code suivant :

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());

Sélectionner plusieurs éléments multimédias

Pour sélectionner plusieurs éléments multimédias, définissez un nombre maximal de fichiers multimédias sélectionnables, comme indiqué dans l'extrait de code suivant.

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());

La plate-forme limite le nombre maximal de fichiers que vous pouvez demander à l'utilisateur de sélectionner dans le sélecteur de photos. Pour accéder à cette limite, appelez getPickImagesMaxLimit(). Cette limite est ignorée sur les appareils ne prenant pas en charge le sélecteur de photos.

Conserver l'accès aux fichiers multimédias

Par défaut, le système autorise votre application à accéder aux fichiers multimédias jusqu'à ce que l'appareil soit redémarré ou jusqu'à ce que votre application s'arrête. Si votre application exécute une opération de longue durée, comme l'importation d'un fichier volumineux en arrière-plan, vous devrez peut-être prolonger cet accès. Pour ce faire, appelez la méthode 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);

Vérifier si le sélecteur de photos est disponible

La section suivante explique comment utiliser une bibliothèque de frameworks pour vérifier si le sélecteur de photos est disponible sur un appareil donné. Ce workflow vous permet de personnaliser le comportement de lancement du sélecteur de photos et de ne pas dépendre de la bibliothèque Support.

Pour utiliser la version fournie par le framework du sélecteur de photos, ajoutez la logique suivante à votre application :

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