Sélecteur de photos intégré

Animation montrant le processus de sélection continue dans le sélecteur de photos

Le sélecteur de photos intégré est une autre forme d'expérience de sélection de photos, qui permet d'interagir directement dans les interfaces utilisateur des applications. Il offre des options d'intégration et de personnalisation améliorées par rapport au sélecteur de photos classique. Comme il est affiché sur un SurfaceView à l'aide de la méthode setChildSurfacePackage, il conserve les mêmes fonctionnalités de sécurité et de confidentialité que la version non intégrée.

Avec le sélecteur de photos intégré, les utilisateurs peuvent sélectionner en continu des photos et des vidéos à partir de leur appareil et de leur bibliothèque photo cloud sans perdre leur concentration dans l'application cliente. L'application cliente reste active, son activité est dans un état repris et peut répondre aux sélections des utilisateurs en temps réel.

Le sélecteur de photos intégré offre une intégration plus fluide de l'UI, mais conserve les mêmes fonctionnalités de sécurité et de confidentialité que le sélecteur de photos standard, car il est affiché sur un SurfaceView spécial.

Disponibilité des appareils

Le sélecteur de photos intégré est compatible avec les appareils équipés d'Android 14 (niveau d'API 34) avec les extensions SDK version 15 ou ultérieure.

Les appareils qui ne correspondent pas à ces fonctionnalités peuvent s'appuyer sur le sélecteur de photos classique ou la version rétroportée à l'aide des services Google Play.

Dépendance de la bibliothèque Jetpack

Incluez la bibliothèque du sélecteur de photos Jetpack en tant que dépendance :

// For apps using Jetpack Compose
implementation("androidx.photopicker:photopicker-compose:1.0.0-alpha01")

// For apps using Views
implementation("androidx.photopicker:photopicker:1.0.0-alpha01")

Vous pouvez intégrer le sélecteur de photos intégré à l'aide de Jetpack Compose (recommandé) ou de Views.

Intégration de Jetpack Compose

La fonction composable EmbeddedPhotoPicker fournit un mécanisme permettant d'inclure l'UI du sélecteur de photos intégré directement dans votre écran Jetpack Compose. Ce composable crée un SurfaceView qui héberge l'UI du sélecteur de photos intégré. Il gère la connexion au service EmbeddedPhotoPicker, gère les interactions utilisateur et communique les URI multimédias sélectionnés à l'application appelante avec peu de paramètres à utiliser :

val coroutineScope = rememberCoroutineScope()
val pickerState = rememberEmbeddedPhotoPickerState()

EmbeddedPhotoPicker(
    state = pickerState,
    onUriPermissionGranted = { uris ->
        _attachments.value += uris
    },
    onUriPermissionRevoked = { uris ->
        _attachments.value -= uris
    },
    onSelectionComplete = {
        // Hide the embedded photo picker as the user is done with the
        // photo/video selection
    },
)

Sélection continue

Animation montrant le processus de sélection continue dans le sélecteur de photos

Le sélecteur de photos intégré permet aux utilisateurs de sélectionner et de désélectionner en continu des éléments de la bibliothèque de photos sans fermer le sélecteur. Les éléments sélectionnés et désélectionnés dans l'UI de l'application sont synchronisés avec le sélecteur de photos, ce qui offre une expérience utilisateur fluide.

Désélectionnez Uri à l'aide de la méthode deselectUri ou deselectUris à partir de pickerState pour informer le sélecteur intégré que l'utilisateur a désélectionné un élément de l'UI de l'application. Il est nécessaire de mettre à jour manuellement l'état de l'UI de votre application, car l'appel de ces méthodes n'informera pas votre application des URI révoqués via le rappel onUriPermissionRevoked.

coroutineScope.launch {
    // Signal unselected media to the picker
    pickerState.deselectUris(uris)
    // Remove them from the list of selected media to be reflected in the app's UI
    _attachments.value -= uris
}

Personnaliser le sélecteur de photos

Le sélecteur de photos intégré offre des options de personnalisation qui vous permettent d'adapter son apparence et son comportement pour mieux l'intégrer à la conception et à l'expérience utilisateur de votre application.

Couleur d'accentuation

Par défaut, le sélecteur de photos intégré s'appuie sur les couleurs dynamiques fournies par le système que l'utilisateur peut définir dans les options de thème de l'appareil. La couleur d'accentuation sera utilisée pour différents éléments principaux du sélecteur de photos. Toutes les autres couleurs seront définies en fonction des consignes Material Design d'Android. Pour personnaliser la couleur d'accentuation du sélecteur, définissez l'option EmbeddedPhotoPickerFeatureInfo :

val info = EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)
Sans définir de couleur d'accentuation Avec couleur d'accentuation (pic) Avec couleur d'accentuation (développé)
Capture d'écran du sélecteur de photos sans couleur d'accentuation définie Capture d'écran du sélecteur de photos avec une couleur d'accentuation (pic) Capture d'écran du sélecteur de photos avec couleur d'accentuation (développé)

La couleur d'accentuation doit être entièrement opaque. La valeur alpha (transparence) est ignorée. Seules les couleurs dont la luminance (luminosité) est comprise entre 0,05 et 0,9 sont autorisées.

Dimensions

Par défaut, la taille du sélecteur intégré n'est pas limitée, mais vous pouvez spécifier un modificateur pour la limiter :

EmbeddedPhotoPicker(
    modifier = Modifier.height(500.dp),
    ...
)
Sans limite (étendu) Avec une limite de 500 dp (développée)
Capture d'écran du sélecteur de photos Capture d'écran du sélecteur de photos

Intégration des vues

Pour ajouter le sélecteur de photos intégré à l'aide de Views, ajoutez une entrée à votre fichier de mise en page :

<view class="androidx.photopicker.EmbeddedPhotoPickerView"
    android:id="@+id/photopicker"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Ensuite, initialisez l'outil de sélection de photos dans la méthode onCreate de votre activité en procédant comme suit :

  1. Obtenir une référence à votre EmbeddedPhotoPickerView à partir de la mise en page
  2. Ajoutez EmbeddedPhotoPickerStateChangeListener pour gérer les événements de sélection.
  3. Configurez le sélecteur de photos avec EmbeddedPhotoPickerFeatureInfo, y compris les paramètres personnalisés tels que la couleur d'accentuation.
// Keep track of the selected media
private val _attachments = MutableStateFlow(emptyList<Uri>())
val attachments = _attachments.asStateFlow()

private lateinit var picker: EmbeddedPhotoPickerView
private var openSession: EmbeddedPhotoPickerSession? = null

val pickerListener = object : EmbeddedPhotoPickerStateChangeListener {
    override fun onSessionOpened(newSession: EmbeddedPhotoPickerSession) {
        // Keep reference to the session to notify the embedded picker of user
        // interactions on the calling app
        openSession = newSession
    }

    override fun onSessionError(throwable: Throwable) {}

    override fun onUriPermissionGranted(uris: List<Uri>) {
        // Add newly selected media to our tracked list
        _attachments += uris
    }

    override fun onUriPermissionRevoked(uris: List<Uri>) {
        // Remove newly unselected media from our tracked list
        _attachments -= uris
    }

    override fun onSelectionComplete() {
        // Hide the embedded photo picker as the user is done with the
        // photo/video selection
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.main_view)
    picker = findViewById(R.id.photopicker)

    // Attach the embedded picker event listener to update the app's UI
    picker.addEmbeddedPhotoPickerStateChangeListener(pickerListener)

    // Customize embedded picker's features: accent color, max selectable items,
    // pre-selected URIs, filter out mime types
    picker.setEmbeddedPhotoPickerFeatureInfo(
        // Set a custom accent color
        EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()
    )
}

Vous pouvez appeler les différentes méthodes de EmbeddedPhotoPickerSession pour interagir avec le sélecteur intégré :

// Notify the embedded picker of a configuration change
openSession.notifyConfigurationChanged(newConfig)

// Update the embedded picker to expand following a user interaction
openSession.notifyPhotoPickerExpanded(/* expanded: */ true)

// Resize the embedded picker
openSession.notifyResized(/* width: */ 512, /* height: */ 256)

// Show/hide the embedded picker (after a form has been submitted)
openSession.notifyVisibilityChanged(/* visible: */ false)

// Remove unselected media from the embedded picker after they have been
// unselected from the host app's UI
openSession.requestRevokeUriPermission(removedUris)