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 consultable qui présente les avec sa bibliothèque multimédia, triée par date, de la plus récente à la plus ancienne. 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.

Les utilisateurs dont l'appareil dispose de fournisseurs multimédias cloud éligibles peuvent également sélectionner des photos et des vidéos stockées à distance. En savoir plus sur les fournisseurs de contenus multimédias cloud

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.

Utiliser des contrats d'activité Jetpack

Pour simplifier l'intégration du sélecteur de photos, incluez la version 1.7.0 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 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());

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

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.

Appareils concernés

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

Les appareils plus anciens équipés d'Android 4.4 (niveau d'API 19) à Android 10 (niveau d'API 29), ainsi que les appareils Android Go exécutant Android 11 ou 12 compatibles avec les services Google Play peuvent installer une version rétroportée du sélecteur de photos. Pour activer l'installation automatique du module de sélecteur de photos rétroporté via les services Google Play, ajoutez l'entrée suivante à la balise <application> dans le fichier manifeste de votre application :

<!-- 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>

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