Recevoir du contenu enrichi

Figure 1. L'API unifiée permet de gérer le contenu entrant dans un seul et même endroit, quel que soit le mécanisme d'UI spécifique, comme le collage à partir du menu "Appuyer de manière prolongée" ou le glisser-déposer.

Les utilisateurs aiment les images, les vidéos et les autres contenus expressifs, mais insérer et déplacer ces contenus dans les applications n'est pas toujours facile. Pour simplifier la réception de contenu enrichi par les applications, Android 12 (niveau d'API 31) introduit une API unifiée qui permet à votre application d'accepter du contenu provenant de n'importe quelle source : presse-papiers, clavier ou glisser-déposer.

Vous pouvez associer une interface, telle que OnReceiveContentListener, aux composants d'interface utilisateur et obtenir un rappel lorsque du contenu est inséré via un mécanisme. Le rappel devient l'unique emplacement où votre code peut gérer la réception de tous les contenus, du texte brut et stylisé au balisage, aux images, aux vidéos, aux fichiers audio, etc.

Pour assurer la rétrocompatibilité avec les versions précédentes d'Android, cette API est également disponible dans AndroidX, à partir de Core 1.7 et AppCompat 1.4, que nous vous recommandons d'utiliser lorsque vous implémentez cette fonctionnalité.

Présentation

Avec les autres API existantes, chaque mécanisme d'UI (tel que le menu "Appuyer de manière prolongée" ou le glisser-déposer) dispose de son propre API correspondante. Cela signifie que vous devez intégrer chaque API séparément, en ajoutant un code similaire pour chaque mécanisme qui insère du contenu :

Figure 2 : Auparavant, les applications implémentaient une API différente pour chaque mécanisme d'UI permettant d'insérer du contenu.

L'API OnReceiveContentListener consolide ces différents chemins de code en créant une seule API à implémenter. Vous pouvez ainsi vous concentrer sur la logique propre à votre application et laisser la plate-forme gérer le reste :

Figure 3 : L'API unifiée vous permet d'implémenter une seule API compatible avec tous les mécanismes d'UI.

Cette approche signifie également que lorsque de nouvelles méthodes d'insertion de contenu sont ajoutées à la plate-forme, vous n'avez pas besoin d'apporter de modifications de code supplémentaires pour activer la prise en charge dans votre application. Et si votre application doit implémenter une personnalisation complète pour un cas d'utilisation particulier, vous pouvez toujours utiliser les API existantes, qui continuent de fonctionner de la même manière.

Implémentation

Remarque : Consultez l'exemple de glisser-déposer pour une implémentation complète de DropHelper, qui implémente OnReceiveContentListener. Pour en savoir plus, consultez le guide sur l'activation du glisser-déposer.

L'API est une interface d'écouteur avec une seule méthode, OnReceiveContentListener. Pour prendre en charge les anciennes versions de la plate-forme Android, nous vous recommandons d'utiliser l'interface OnReceiveContentListener correspondante dans la bibliothèque AndroidX Core.

Pour utiliser l'API, implémentez l'écouteur en spécifiant les types de contenu que votre application peut gérer :

Kotlin

object MyReceiver : OnReceiveContentListener {
    val MIME_TYPES = arrayOf("image/*", "video/*")
    
    // ...
    
    override fun onReceiveContent(view: View, payload: ContentInfoCompat): ContentInfoCompat? {
        TODO("Not yet implemented")
    }
}

Java

public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};
     // ...
}

Après avoir spécifié tous les types de contenu MIME compatibles avec votre application, implémentez le reste de l'écouteur :

Kotlin

class MyReceiver : OnReceiveContentListener {
    override fun onReceiveContent(view: View, contentInfo: ContentInfoCompat): ContentInfoCompat {
        val split = contentInfo.partition { item: ClipData.Item -> item.uri != null }
        val uriContent = split.first
        val remaining = split.second
        if (uriContent != null) {
            // App-specific logic to handle the URI(s) in uriContent.
        }
        // Return anything that your app didn't handle. This preserves the
        // default platform behavior for text and anything else that you aren't
        // implementing custom handling for.
        return remaining
    }

    companion object {
        val MIME_TYPES = arrayOf("image/*", "video/*")
    }
}

Java

 public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};

     @Override
     public ContentInfoCompat onReceiveContent(View view, ContentInfoCompat contentInfo) {
         Pair<ContentInfoCompat, ContentInfoCompat> split = contentInfo.partition(
                 item -> item.getUri() != null);
         ContentInfo uriContent = split.first;
         ContentInfo remaining = split.second;
         if (uriContent != null) {
             // App-specific logic to handle the URI(s) in uriContent.
         }
         // Return anything that your app didn't handle. This preserves the
         // default platform behavior for text and anything else that you aren't
         // implementing custom handling for.
         return remaining;
     }
 }

Si votre application est déjà compatible avec le partage avec des intents, vous pouvez réutiliser votre logique spécifique à l'application pour gérer les URI de contenu. Renvoyez les données restantes pour déléguer la gestion de ces données à la plate-forme.

Après avoir implémenté l'écouteur, définissez-le sur les éléments d'interface utilisateur appropriés de votre application :

Kotlin

class MyActivity : Activity() {
    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        val myInput = findViewById(R.id.my_input)
        ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, MyReceiver())
    }
}

Java

public class MyActivity extends Activity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
         // ...

         AppCompatEditText myInput = findViewById(R.id.my_input);
         ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, new MyReceiver());
     }
}

Autorisations d'URI

Les autorisations de lecture sont accordées et libérées automatiquement par la plate-forme pour tous les URI de contenu présents dans la charge utile transmise à OnReceiveContentListener.

Normalement, votre application traite les URI de contenu dans un service ou une activité. Pour le traitement de longue durée, utilisez WorkManager. Lorsque vous implémentez cette méthode, étendez les autorisations au service ou à l'activité cibles en transmettant le contenu à l'aide de Intent.setClipData et en définissant l'option FLAG_GRANT_READ_URI_PERMISSION.

Vous pouvez également utiliser un thread en arrière-plan dans le contexte actuel pour traiter le contenu. Dans ce cas, vous devez conserver une référence à l'objet payload reçu par l'écouteur pour vous assurer que les autorisations ne sont pas révoquées prématurément par la plate-forme.

Vues personnalisées

Si votre application utilise une sous-classe View personnalisée, veillez à ce que OnReceiveContentListener ne soit pas contourné.

Si votre classe View remplace la méthode onCreateInputConnection, utilisez l'API Jetpack InputConnectionCompat.createWrapper pour configurer InputConnection.

Si votre classe View remplace la méthode onTextContextMenuItem, déléguez à "super" lorsque l'élément de menu est R.id.paste ou R.id.pasteAsPlainText.

Comparaison avec l'API d'image du clavier

Vous pouvez considérer l'API OnReceiveContentListener comme la prochaine version de l'API d'image clavier existante. Cette API unifiée est compatible avec les fonctionnalités de l'API d'image du clavier, ainsi qu'avec certaines fonctionnalités supplémentaires. La compatibilité des appareils et des fonctionnalités varie selon que vous utilisez la bibliothèque Jetpack ou les API natives du SDK Android.

Tableau 1. Fonctionnalités et niveaux d'API compatibles avec Jetpack.

Action ou fonctionnalité	Prise en charge par l'API d'image du clavier	Compatible avec l'API unifiée
Insérer depuis le clavier	Oui (niveau d'API 13 ou version ultérieure)	Oui (niveau d'API 13 ou version ultérieure)
Insérer du texte en collant à partir du menu d'appui prolongé	Non	Oui
Insérer par glisser-déposer	Non	Oui (niveau d'API 24 ou version ultérieure)

Tableau 2. Fonctionnalités et niveaux d'API compatibles pour les API natives.

Action ou fonctionnalité	Prise en charge par l'API d'image du clavier	Compatible avec l'API unifiée
Insérer à partir du clavier	Oui (niveau d'API 25 ou supérieur)	Oui (Android 12 ou version ultérieure)
Insérer en appuyant de manière prolongée sur le menu	Non
Insérer par glisser-déposer	Non