Copier et coller

Android fournit un framework puissant basé sur un presse-papiers pour copier et coller. Elle est compatible avec les types de données simples et complexes, comme les chaînes de texte, les structures de données complexes, les données de flux textuelles et binaires, ainsi que les éléments d'application. Les données textuelles simples sont stockées directement dans le presse-papiers, tandis que les données complexes sont stockées en tant que référence que l'application de collage résout avec un fournisseur de contenu. Le copier-coller fonctionne à la fois au sein d'une application et entre les applications qui mettent en œuvre le framework.

Étant donné qu'une partie du framework utilise des fournisseurs de contenu, ce document suppose une certaine connaissance de l'API Android Content Provider, décrite dans la section Fournisseurs de contenu.

Les utilisateurs s'attendent à recevoir des commentaires lorsqu'ils copient du contenu dans le presse-papiers. Par conséquent, en plus du framework qui permet de copier-coller, Android affiche une UI par défaut aux utilisateurs lorsqu'ils copient du contenu dans Android 13 (niveau d'API 33) ou version ultérieure. Cette fonctionnalité peut entraîner des notifications en double. Pour en savoir plus sur ce cas limite, consultez la section Éviter les notifications en double.

Animation montrant la notification du presse-papiers d'Android 13
Figure 1 : UI affichée lorsque le contenu entre dans le presse-papiers sous Android 13 ou version ultérieure

Envoyez manuellement des commentaires aux utilisateurs lors de la copie sous Android 12L (niveau d'API 32) ou version antérieure. Consultez les recommandations à ce sujet dans ce document.

Framework pour le presse-papiers

Lorsque vous utilisez le framework du presse-papiers, placez les données dans un objet Clip, puis placez cet objet dans le presse-papiers à l'échelle du système. L'objet clip peut prendre l'une des trois formes suivantes:

Texte
Chaîne de texte. Placez la chaîne directement dans l'objet clip, que vous placez ensuite dans le presse-papiers. Pour coller la chaîne, récupérez l'objet Clip dans le presse-papiers et copiez la chaîne dans l'espace de stockage de votre application.
URI
Un objet Uri représentant n'importe quelle forme d'URI. Cela permet principalement de copier des données complexes à partir d'un fournisseur de contenu. Pour copier des données, placez un objet Uri dans un objet clip et placez-le dans le presse-papiers. Pour coller les données, récupérez l'objet Clip, récupérez l'objet Uri, résolvez-le vers une source de données, telle qu'un fournisseur de contenu, puis copiez les données de la source dans l'espace de stockage de votre application.
Intent
Un Intent. Cette fonctionnalité permet de copier les raccourcis d'application. Pour copier des données, créez un Intent, placez-le dans un objet clip, puis placez cet objet clip dans le presse-papiers. Pour coller les données, récupérez l'objet Extrait, puis copiez l'objet Intent dans la zone de mémoire de votre application.

Le presse-papiers ne contient qu'un seul objet clip à la fois. Lorsqu'une application place un objet clip dans le presse-papiers, l'objet clip précédent disparaît.

Si vous souhaitez autoriser les utilisateurs à coller des données dans votre application, vous n'avez pas à gérer tous les types de données. Vous pouvez examiner les données du presse-papiers avant de donner aux utilisateurs la possibilité de les coller. En plus d'avoir un certain format de données, l'objet clip contient également des métadonnées qui vous indiquent les types MIME disponibles. Ces métadonnées vous aident à décider si votre application peut effectuer quelque chose d'utile avec les données du presse-papiers. Par exemple, si votre application gère principalement du texte, vous pouvez ignorer les objets clip qui contiennent un URI ou un intent.

Vous pouvez également autoriser les utilisateurs à coller du texte, quelle que soit la forme des données dans le presse-papiers. Pour ce faire, forcez les données du presse-papiers dans une représentation textuelle, puis collez ce texte. Ceci est décrit dans la section Convertir le presse-papiers en texte.

Classes du presse-papiers

Cette section décrit les classes utilisées par le framework du presse-papiers.

Gestionnaire Presse-papiers

Le presse-papiers du système Android est représenté par la classe globale ClipboardManager. N'instanciez pas cette classe directement. À la place, obtenez une référence en appelant getSystemService(CLIPBOARD_SERVICE).

ClipData, ClipData.Item et ClipDescription

Pour ajouter des données au presse-papiers, créez un objet ClipData contenant une description des données et des données elles-mêmes. Le presse-papiers contient un élément ClipData à la fois. Un ClipData contient un objet ClipDescription et un ou plusieurs objets ClipData.Item.

Un objet ClipDescription contient des métadonnées sur l'extrait. Il contient en particulier un tableau des types MIME disponibles pour les données du clip. De plus, sur Android 12 (niveau d'API 31) ou version ultérieure, les métadonnées incluent des informations indiquant si l'objet contient du texte stylisé et sur le type de texte qu'il contient. Lorsque vous placez un extrait dans le presse-papiers, ces informations sont disponibles pour les applications de collage, qui peuvent examiner si elles peuvent gérer les données de l'extrait.

Un objet ClipData.Item contient les données de texte, d'URI ou d'intent:

Texte
Un CharSequence.
URI
Un Uri. Il contient généralement un URI de fournisseur de contenu, bien que n'importe quel URI est autorisé. L'application qui fournit les données place l'URI dans le presse-papiers. Les applications qui souhaitent coller les données récupèrent l'URI du presse-papiers et l'utilisent pour accéder au fournisseur de contenu ou à une autre source de données, et récupérer les données.
Intent
Un Intent. Ce type de données vous permet de copier un raccourci d'application dans le presse-papiers. Les utilisateurs peuvent ensuite coller le raccourci dans leurs applications pour une utilisation ultérieure.

Vous pouvez ajouter plusieurs objets ClipData.Item à un extrait. Cela permet aux utilisateurs de copier et coller plusieurs sélections en un seul extrait. Par exemple, si vous disposez d'un widget de liste qui permet à l'utilisateur de sélectionner plusieurs éléments à la fois, vous pouvez copier tous les éléments en une seule fois dans le presse-papiers. Pour ce faire, créez une ClipData.Item distincte pour chaque élément de la liste, puis ajoutez les objets ClipData.Item à l'objet ClipData.

Méthodes de commodité ClipData

La classe ClipData fournit des méthodes pratiques statiques pour créer un objet ClipData avec un seul objet ClipData.Item et un objet ClipDescription simple:

newPlainText(label, text)
Renvoie un objet ClipData dont l'objet ClipData.Item unique contient une chaîne de texte. Le libellé de l'objet ClipDescription est défini sur label. Le type MIME unique dans ClipDescription est MIMETYPE_TEXT_PLAIN.

Utilisez newPlainText() pour créer un extrait à partir d'une chaîne de texte.

newUri(resolver, label, URI)
Renvoie un objet ClipData dont l'objet ClipData.Item unique contient un URI. Le libellé de l'objet ClipDescription est défini sur label. Si l'URI est un URI de contenu, c'est-à-dire si Uri.getScheme() renvoie content:, la méthode utilise l'objet ContentResolver fourni dans resolver pour récupérer les types MIME disponibles auprès du fournisseur de contenu. Il les stocke ensuite dans ClipDescription. Pour un URI qui n'est pas un URI content:, la méthode définit le type MIME sur MIMETYPE_TEXT_URILIST.

Utilisez newUri() pour créer un extrait à partir d'un URI, en particulier un URI content:.

newIntent(label, intent)
Renvoie un objet ClipData dont l'objet ClipData.Item unique contient un Intent. Le libellé de l'objet ClipDescription est défini sur label. Le type MIME est défini sur MIMETYPE_TEXT_INTENT.

Utilisez newIntent() pour créer un extrait à partir d'un objet Intent.

Convertir les données du presse-papiers en texte

Même si votre application ne gère que du texte, vous pouvez copier des données non textuelles depuis le presse-papiers en les convertissant avec la méthode ClipData.Item.coerceToText().

Cette méthode convertit les données de ClipData.Item en texte et renvoie un CharSequence. La valeur renvoyée par ClipData.Item.coerceToText() est basée sur le format des données présentes dans ClipData.Item:

Texte
Si ClipData.Item est du texte, c'est-à-dire si getText() n'est pas nul, forçageToText() renvoie le texte.
URI
Si ClipData.Item est un URI, c'est-à-dire si getUri() n'est pas nul, coerceToText() tente de l'utiliser comme URI de contenu.
  • Si l'URI est un URI de contenu et que le fournisseur peut renvoyer un flux de texte, coerceToText() renvoie un flux de texte.
  • Si l'URI est un URI de contenu, mais que le fournisseur ne propose pas de flux de texte, coerceToText() renvoie une représentation de l'URI. La représentation est identique à celle renvoyée par Uri.toString().
  • Si l'URI n'est pas un URI de contenu, coerceToText() renvoie une représentation de l'URI. La représentation est identique à celle renvoyée par Uri.toString().
Intent
Si ClipData.Item est une Intent, c'est-à-dire si getIntent() n'est pas nul, coerceToText() le convertit en URI d'intent et le renvoie. La représentation est identique à celle renvoyée par Intent.toUri(URI_INTENT_SCHEME).

Le framework du presse-papiers est résumé dans la figure 2. Pour copier des données, une application place un objet ClipData dans le presse-papiers global ClipboardManager. ClipData contient un ou plusieurs objets ClipData.Item et un objet ClipDescription. Pour coller des données, une application obtient le ClipData, obtient son type MIME à partir de ClipDescription, et obtient les données de ClipData.Item ou du fournisseur de contenu désigné par ClipData.Item.

Image montrant un diagramme de blocs du framework de copier-coller
Figure 2 : Framework de presse-papiers Android.

Copier dans le presse-papiers

Pour copier des données dans le presse-papiers, obtenez un handle vers l'objet ClipboardManager global, créez un objet ClipData, puis ajoutez-y un ClipDescription et un ou plusieurs objets ClipData.Item. Ajoutez ensuite l'objet ClipData terminé à l'objet ClipboardManager. Ce processus est décrit plus en détail dans la procédure suivante:

  1. Si vous copiez des données à l'aide d'un URI de contenu, configurez un fournisseur de contenu.
  2. Téléchargez le presse-papiers du système:

    Kotlin

    when(menuItem.itemId) {
        ...
        R.id.menu_copy -> { // if the user selects copy
            // Gets a handle to the clipboard service.
            val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
        }
    }
    

    Java

    ...
    // If the user selects copy.
    case R.id.menu_copy:
    
    // Gets a handle to the clipboard service.
    ClipboardManager clipboard = (ClipboardManager)
            getSystemService(Context.CLIPBOARD_SERVICE);
    
  3. Copiez les données dans un nouvel objet ClipData:

    • Texte

      Kotlin

      // Creates a new text clip to put on the clipboard.
      val clip: ClipData = ClipData.newPlainText("simple text", "Hello, World!")
      

      Java

      // Creates a new text clip to put on the clipboard.
      ClipData clip = ClipData.newPlainText("simple text", "Hello, World!");
      
    • Pour un URI

      Cet extrait construit un URI en encodant un ID d'enregistrement dans l'URI de contenu du fournisseur. Cette technique est abordée plus en détail dans la section Encoder un identifiant dans l'URI.

      Kotlin

      // Creates a Uri using a base Uri and a record ID based on the contact's last
      // name. Declares the base URI string.
      const val CONTACTS = "content://com.example.contacts"
      
      // Declares a path string for URIs, used to copy data.
      const val COPY_PATH = "/copy"
      
      // Declares the Uri to paste to the clipboard.
      val copyUri: Uri = Uri.parse("$CONTACTS$COPY_PATH/$lastName")
      ...
      // Creates a new URI clip object. The system uses the anonymous
      // getContentResolver() object to get MIME types from provider. The clip object's
      // label is "URI", and its data is the Uri previously created.
      val clip: ClipData = ClipData.newUri(contentResolver, "URI", copyUri)
      

      Java

      // Creates a Uri using a base Uri and a record ID based on the contact's last
      // name. Declares the base URI string.
      private static final String CONTACTS = "content://com.example.contacts";
      
      // Declares a path string for URIs, used to copy data.
      private static final String COPY_PATH = "/copy";
      
      // Declares the Uri to paste to the clipboard.
      Uri copyUri = Uri.parse(CONTACTS + COPY_PATH + "/" + lastName);
      ...
      // Creates a new URI clip object. The system uses the anonymous
      // getContentResolver() object to get MIME types from provider. The clip object's
      // label is "URI", and its data is the Uri previously created.
      ClipData clip = ClipData.newUri(getContentResolver(), "URI", copyUri);
      
    • Pour un intent

      Cet extrait construit un Intent pour une application, puis le place dans l'objet clip:

      Kotlin

      // Creates the Intent.
      val appIntent = Intent(this, com.example.demo.myapplication::class.java)
      ...
      // Creates a clip object with the Intent in it. Its label is "Intent"
      // and its data is the Intent object created previously.
      val clip: ClipData = ClipData.newIntent("Intent", appIntent)
      

      Java

      // Creates the Intent.
      Intent appIntent = new Intent(this, com.example.demo.myapplication.class);
      ...
      // Creates a clip object with the Intent in it. Its label is "Intent"
      // and its data is the Intent object created previously.
      ClipData clip = ClipData.newIntent("Intent", appIntent);
      
  4. Placer le nouvel objet clip dans le presse-papiers:

    Kotlin

    // Set the clipboard's primary clip.
    clipboard.setPrimaryClip(clip)
    

    Java

    // Set the clipboard's primary clip.
    clipboard.setPrimaryClip(clip);
    

Envoyer des commentaires lors de la copie dans le presse-papiers

Les utilisateurs s'attendent à recevoir un retour visuel lorsqu'une application copie du contenu dans le presse-papiers. Cette opération s'effectue automatiquement pour les utilisateurs d'Android 13 ou version ultérieure, mais doit être implémentée manuellement dans les versions précédentes.

À partir d'Android 13, le système affiche une confirmation visuelle standard lorsque du contenu est ajouté au presse-papiers. La nouvelle confirmation effectue les opérations suivantes:

  • Confirmez que le contenu a bien été copié.
  • Fournit un aperçu du contenu copié.

Animation montrant la notification du presse-papiers d'Android 13
Figure 3 : UI affichée lorsque le contenu entre dans le presse-papiers sous Android 13 ou version ultérieure

Dans Android 12L (niveau d'API 32) et versions antérieures, les utilisateurs peuvent ne pas savoir s'ils ont réussi à copier du contenu ou ce qu'ils ont copié. Cette fonctionnalité standardise les différentes notifications affichées par les applications après la copie et offre aux utilisateurs plus de contrôle sur le presse-papiers.

Éviter les notifications en double

Dans Android 12L (niveau d'API 32) et versions antérieures, après la copie, nous vous recommandons d'alerter les utilisateurs en émettant des commentaires visuels dans l'application à l'aide d'un widget tel que Toast ou Snackbar.

Pour éviter l'affichage d'informations en double, nous vous recommandons vivement de supprimer les toasts ou les snackbars affichés après une copie dans l'application pour Android 13 ou version ultérieure.

Publiez le snackbar après une copie dans l'application.
Figure 4 : Si vous affichez un snackbar de confirmation de copie dans Android 13, l'utilisateur voit des messages en double.
Publier un toast après une copie dans l'application
Figure 5 : Si vous affichez un toast de confirmation de copie dans Android 13, l'utilisateur voit des messages en double.

Voici un exemple de mise en œuvre:

fun textCopyThenPost(textCopied:String) {
    val clipboardManager = getSystemService(CLIPBOARD_SERVICE) as ClipboardManager
    // When setting the clipboard text.
    clipboardManager.setPrimaryClip(ClipData.newPlainText   ("", textCopied))
    // Only show a toast for Android 12 and lower.
    if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.S_V2)
        Toast.makeText(context, “Copied”, Toast.LENGTH_SHORT).show()
}

Ajouter du contenu sensible au presse-papiers

Si votre application permet aux utilisateurs de copier du contenu sensible dans le presse-papiers, comme des mots de passe ou des informations de carte de crédit, vous devez ajouter un indicateur à ClipDescription dans ClipData avant d'appeler ClipboardManager.setPrimaryClip(). L'ajout de cet indicateur empêche le contenu sensible d'apparaître dans la confirmation visuelle du contenu copié sous Android 13 ou version ultérieure.

Aperçu du texte copié sans signaler de contenu sensible
Figure 6. Aperçu du texte copié sans indicateur de contenu sensible.
Aperçu du texte copié signalant du contenu sensible.
Figure 7 : Aperçu du texte copié avec un indicateur de contenu sensible.

Pour signaler du contenu sensible, ajoutez une valeur booléenne supplémentaire à ClipDescription. Toutes les applications doivent le faire, quel que soit le niveau d'API ciblé.

// If your app is compiled with the API level 33 SDK or higher.
clipData.apply {
    description.extras = PersistableBundle().apply {
        putBoolean(ClipDescription.EXTRA_IS_SENSITIVE, true)
    }
}

// If your app is compiled with a lower SDK.
clipData.apply {
    description.extras = PersistableBundle().apply {
        putBoolean("android.content.extra.IS_SENSITIVE", true)
    }
}

Coller depuis le presse-papiers

Comme décrit précédemment, collez les données du presse-papiers en récupérant l'objet du presse-papiers global, en consultant ses données et, si possible, en les copiant dans votre propre espace de stockage. Cette section explique en détail comment coller les trois types de données du presse-papiers.

Coller le texte brut

Pour coller du texte brut, récupérez le presse-papiers global et vérifiez qu'il peut renvoyer du texte brut. Récupérez ensuite l'objet clip et copiez son texte sur votre propre espace de stockage à l'aide de getText(), comme décrit dans la procédure suivante:

  1. Obtenez l'objet ClipboardManager global à l'aide de getSystemService(CLIPBOARD_SERVICE). Déclarez également une variable globale pour contenir le texte collé:

    Kotlin

    var clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    var pasteData: String = ""
    

    Java

    ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
    String pasteData = "";
    
  2. Déterminez si vous devez activer ou désactiver l'option "Coller" dans l'activité actuelle. Vérifiez que le presse-papiers contient un extrait et que vous pouvez gérer le type de données représenté par celui-ci:

    Kotlin

    // Gets the ID of the "paste" menu item.
    val pasteItem: MenuItem = menu.findItem(R.id.menu_paste)
    
    // If the clipboard doesn't contain data, disable the paste menu item.
    // If it does contain data, decide whether you can handle the data.
    pasteItem.isEnabled = when {
        !clipboard.hasPrimaryClip() -> {
            false
        }
        !(clipboard.primaryClipDescription.hasMimeType(MIMETYPE_TEXT_PLAIN)) -> {
            // Disables the paste menu item, since the clipboard has data but it
            // isn't plain text.
            false
        }
        else -> {
            // Enables the paste menu item, since the clipboard contains plain text.
            true
        }
    }
    

    Java

    // Gets the ID of the "paste" menu item.
    MenuItem pasteItem = menu.findItem(R.id.menu_paste);
    
    // If the clipboard doesn't contain data, disable the paste menu item.
    // If it does contain data, decide whether you can handle the data.
    if (!(clipboard.hasPrimaryClip())) {
    
        pasteItem.setEnabled(false);
    
    } else if (!(clipboard.getPrimaryClipDescription().hasMimeType(MIMETYPE_TEXT_PLAIN))) {
    
        // Disables the paste menu item, since the clipboard has data but
        // it isn't plain text.
        pasteItem.setEnabled(false);
    } else {
    
        // Enables the paste menu item, since the clipboard contains plain text.
        pasteItem.setEnabled(true);
    }
    
  3. Copiez les données du presse-papiers. Ce point du code n'est accessible que si l'élément de menu "Coller" est activé. Vous pouvez donc supposer que le presse-papiers contient du texte brut. Vous ne savez pas encore si elle contient une chaîne de texte ou un URI pointant vers du texte brut. L'extrait de code suivant le teste, mais il n'affiche que le code permettant de gérer le texte brut:

    Kotlin

    when (menuItem.itemId) {
        ...
        R.id.menu_paste -> {    // Responds to the user selecting "paste".
            // Examines the item on the clipboard. If getText() doesn't return null,
            // the clip item contains the text. Assumes that this application can only
            // handle one item at a time.
            val item = clipboard.primaryClip.getItemAt(0)
    
            // Gets the clipboard as text.
            pasteData = item.text
    
            return if (pasteData != null) {
                // If the string contains data, then the paste operation is done.
                true
            } else {
                // The clipboard doesn't contain text. If it contains a URI,
                // attempts to get data from it.
                val pasteUri: Uri? = item.uri
    
                if (pasteUri != null) {
                    // If the URI contains something, try to get text from it.
    
                    // Calls a routine to resolve the URI and get data from it.
                    // This routine isn't presented here.
                    pasteData = resolveUri(pasteUri)
                    true
                } else {
    
                    // Something is wrong. The MIME type was plain text, but the
                    // clipboard doesn't contain text or a Uri. Report an error.
                    Log.e(TAG,"Clipboard contains an invalid data type")
                    false
                }
            }
        }
    }
    

    Java

    // Responds to the user selecting "paste".
    case R.id.menu_paste:
    
    // Examines the item on the clipboard. If getText() does not return null,
    // the clip item contains the text. Assumes that this application can only
    // handle one item at a time.
     ClipData.Item item = clipboard.getPrimaryClip().getItemAt(0);
    
    // Gets the clipboard as text.
    pasteData = item.getText();
    
    // If the string contains data, then the paste operation is done.
    if (pasteData != null) {
        return true;
    
    // The clipboard doesn't contain text. If it contains a URI, attempts to get
    // data from it.
    } else {
        Uri pasteUri = item.getUri();
    
        // If the URI contains something, try to get text from it.
        if (pasteUri != null) {
    
            // Calls a routine to resolve the URI and get data from it.
            // This routine isn't presented here.
            pasteData = resolveUri(Uri);
            return true;
        } else {
    
            // Something is wrong. The MIME type is plain text, but the
            // clipboard doesn't contain text or a Uri. Report an error.
            Log.e(TAG, "Clipboard contains an invalid data type");
            return false;
        }
    }
    

Coller les données à partir d'un URI de contenu

Si l'objet ClipData.Item contient un URI de contenu et que vous déterminez que vous pouvez gérer l'un de ses types MIME, créez un ContentResolver et appelez la méthode du fournisseur de contenu appropriée pour récupérer les données.

La procédure suivante explique comment obtenir des données auprès d'un fournisseur de contenu en fonction d'un URI de contenu stocké dans le presse-papiers. Il vérifie si un type MIME que l'application peut utiliser est disponible auprès du fournisseur.

  1. Déclarez une variable globale qui contiendra le type MIME:

    Kotlin

    // Declares a MIME type constant to match against the MIME types offered
    // by the provider.
    const val MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"
    

    Java

    // Declares a MIME type constant to match against the MIME types offered by
    // the provider.
    public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact";
    
  2. Récupérez le presse-papiers général. Procurez-vous également un résolveur de contenu pour accéder au fournisseur de contenu:

    Kotlin

    // Gets a handle to the Clipboard Manager.
    val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    
    // Gets a content resolver instance.
    val cr = contentResolver
    

    Java

    // Gets a handle to the Clipboard Manager.
    ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
    
    // Gets a content resolver instance.
    ContentResolver cr = getContentResolver();
    
  3. Récupérez l'extrait principal à partir du presse-papiers et récupérez son contenu sous la forme d'un URI:

    Kotlin

    // Gets the clipboard data from the clipboard.
    val clip: ClipData? = clipboard.primaryClip
    
    clip?.run {
    
        // Gets the first item from the clipboard data.
        val item: ClipData.Item = getItemAt(0)
    
        // Tries to get the item's contents as a URI.
        val pasteUri: Uri? = item.uri
    

    Java

    // Gets the clipboard data from the clipboard.
    ClipData clip = clipboard.getPrimaryClip();
    
    if (clip != null) {
    
        // Gets the first item from the clipboard data.
        ClipData.Item item = clip.getItemAt(0);
    
        // Tries to get the item's contents as a URI.
        Uri pasteUri = item.getUri();
    
  4. Vérifiez si l'URI est un URI de contenu en appelant getType(Uri). Cette méthode renvoie la valeur "null" si Uri ne pointe pas vers un fournisseur de contenu valide.

    Kotlin

        // If the clipboard contains a URI reference...
        pasteUri?.let {
    
            // ...is this a content URI?
            val uriMimeType: String? = cr.getType(it)
    

    Java

        // If the clipboard contains a URI reference...
        if (pasteUri != null) {
    
            // ...is this a content URI?
            String uriMimeType = cr.getType(pasteUri);
    
  5. Vérifiez si le fournisseur de contenu accepte un type MIME compatible avec l'application. Le cas échéant, appelez ContentResolver.query() pour obtenir les données. La valeur renvoyée est Cursor.

    Kotlin

            // If the return value isn't null, the Uri is a content Uri.
            uriMimeType?.takeIf {
    
                // Does the content provider offer a MIME type that the current
                // application can use?
                it == MIME_TYPE_CONTACT
            }?.apply {
    
                // Get the data from the content provider.
                cr.query(pasteUri, null, null, null, null)?.use { pasteCursor ->
    
                    // If the Cursor contains data, move to the first record.
                    if (pasteCursor.moveToFirst()) {
    
                        // Get the data from the Cursor here.
                        // The code varies according to the format of the data model.
                    }
    
                    // Kotlin `use` automatically closes the Cursor.
                }
            }
        }
    }
    

    Java

            // If the return value isn't null, the Uri is a content Uri.
            if (uriMimeType != null) {
    
                // Does the content provider offer a MIME type that the current
                // application can use?
                if (uriMimeType.equals(MIME_TYPE_CONTACT)) {
    
                    // Get the data from the content provider.
                    Cursor pasteCursor = cr.query(uri, null, null, null, null);
    
                    // If the Cursor contains data, move to the first record.
                    if (pasteCursor != null) {
                        if (pasteCursor.moveToFirst()) {
    
                        // Get the data from the Cursor here.
                        // The code varies according to the format of the data model.
                        }
                    }
    
                    // Close the Cursor.
                    pasteCursor.close();
                 }
             }
         }
    }
    

Coller un intent

Pour coller un intent, commencez par récupérer le presse-papiers global. Examinez l'objet ClipData.Item pour vérifier s'il contient un élément Intent. Appelez ensuite getIntent() pour copier l'intent dans votre propre espace de stockage. L'extrait de code suivant le démontre :

Kotlin

// Gets a handle to the Clipboard Manager.
val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager

// Checks whether the clip item contains an Intent by testing whether
// getIntent() returns null.
val pasteIntent: Intent? = clipboard.primaryClip?.getItemAt(0)?.intent

if (pasteIntent != null) {

    // Handle the Intent.

} else {

    // Ignore the clipboard, or issue an error if
    // you expect an Intent to be on the clipboard.
}

Java

// Gets a handle to the Clipboard Manager.
ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);

// Checks whether the clip item contains an Intent, by testing whether
// getIntent() returns null.
Intent pasteIntent = clipboard.getPrimaryClip().getItemAt(0).getIntent();

if (pasteIntent != null) {

    // Handle the Intent.

} else {

    // Ignore the clipboard, or issue an error if
    // you expect an Intent to be on the clipboard.
}

Notification système affichée lorsque votre application accède aux données du presse-papiers

Sur Android 12 (niveau d'API 31) ou version ultérieure, le système affiche généralement un toast lorsque votre application appelle getPrimaryClip(). Le texte qu'il contient présente le format suivant:

APP pasted from your clipboard

Le système n'affiche pas de toast lorsque votre application effectue l'une des opérations suivantes:

  • Accède à ClipData depuis votre propre application.
  • Accède à ClipData de manière répétée à partir d'une application spécifique. Le toast ne s'affiche que lorsque votre application accède aux données de cette application pour la première fois.
  • Récupère les métadonnées de l'objet clip, par exemple en appelant getPrimaryClipDescription() au lieu de getPrimaryClip().

Copier des données complexes à l'aide de fournisseurs de contenu

Les fournisseurs de contenu permettent de copier des données complexes, telles que des enregistrements de base de données ou des flux de fichiers. Pour copier les données, placez un URI de contenu dans le presse-papiers. Lorsque vous collez des applications, vous récupérez cet URI à partir du presse-papiers et l'utilisez pour récupérer des données de base de données ou des descripteurs de flux de fichiers.

Étant donné que l'application de collage ne dispose que de l'URI de contenu de vos données, elle doit savoir quelles données récupérer. Vous pouvez fournir ces informations en encodant un identifiant pour les données sur l'URI lui-même, ou vous pouvez fournir un URI unique qui renvoie les données que vous souhaitez copier. La technique que vous choisissez dépend de l'organisation de vos données.

Les sections suivantes décrivent comment configurer des URI, fournir des données complexes et fournir des flux de fichiers. Les descriptions supposent que vous connaissez les principes généraux de la conception de fournisseurs de contenu.

Encoder un identifiant sur l'URI

Une technique utile pour copier des données dans le presse-papiers avec un URI consiste à encoder un identifiant pour les données dans l'URI lui-même. Votre fournisseur de contenu peut ensuite obtenir l'identifiant à partir de l'URI et l'utiliser pour récupérer les données. L'application de collage n'a pas besoin de savoir que l'identifiant existe. Il doit simplement récupérer votre "référence" (l'URI et l'identifiant) dans le presse-papiers, lui attribuer votre fournisseur de contenu et récupérer les données.

En général, vous encodez un identifiant dans un URI de contenu en le concaténant à la fin de l'URI. Par exemple, supposons que vous définissiez l'URI de votre fournisseur comme la chaîne suivante:

"content://com.example.contacts"

Si vous souhaitez encoder un nom dans cet URI, utilisez l'extrait de code suivant:

Kotlin

val uriString = "content://com.example.contacts/Smith"

// uriString now contains content://com.example.contacts/Smith.

// Generates a uri object from the string representation.
val copyUri = Uri.parse(uriString)

Java

String uriString = "content://com.example.contacts" + "/" + "Smith";

// uriString now contains content://com.example.contacts/Smith.

// Generates a uri object from the string representation.
Uri copyUri = Uri.parse(uriString);

Si vous utilisez déjà un fournisseur de contenu, vous pouvez ajouter un chemin d'URI indiquant que l'URI est destiné à la copie. Par exemple, supposons que vous disposiez déjà des chemins d'URI suivants:

"content://com.example.contacts/people"
"content://com.example.contacts/people/detail"
"content://com.example.contacts/people/images"

Vous pouvez ajouter un autre chemin pour la copie des URI:

"content://com.example.contacts/copying"

Vous pouvez ensuite détecter un URI "copier" en effectuant une correspondance de modèle et le gérer avec du code spécifique au copier-coller.

Vous utilisez normalement la technique d'encodage si vous organisez déjà vos données à l'aide d'un fournisseur de contenu, d'une base de données interne ou d'une table interne. Dans ce cas, vous devez copier plusieurs données et, vraisemblablement, un identifiant unique pour chaque élément. En réponse à une requête de l'application de collage, vous pouvez rechercher les données par leur identifiant et les renvoyer.

Si vous ne disposez pas de plusieurs éléments de données, vous n'avez probablement pas besoin d'encoder un identifiant. Vous pouvez utiliser un URI propre à votre fournisseur. En réponse à une requête, votre fournisseur renvoie les données qu'il contient actuellement.

Copier des structures de données

Configurez un fournisseur de contenu pour copier et coller des données complexes en tant que sous-classe du composant ContentProvider. Encodez l'URI que vous placez dans le presse-papiers afin qu'il pointe vers l'enregistrement exact que vous souhaitez fournir. En outre, tenez compte de l'état actuel de votre application:

  • Si vous avez déjà un fournisseur de contenu, vous pouvez améliorer sa fonctionnalité. Vous devrez peut-être uniquement modifier sa méthode query() pour gérer les URI provenant d'applications qui souhaitent coller des données. Vous souhaiterez probablement modifier la méthode pour gérer un modèle d'URI "copy".
  • Si votre application gère une base de données interne, vous pouvez déplacer cette base de données vers un fournisseur de contenu pour faciliter la copie de celle-ci.
  • Si vous n'utilisez pas de base de données, vous pouvez implémenter un fournisseur de contenu simple dont le seul objectif est de proposer des données aux applications qui sont collées depuis le presse-papiers.

Dans le fournisseur de contenu, remplacez au moins les méthodes suivantes:

query()
Lorsque vous collez des applications, nous partons du principe qu'elles peuvent récupérer vos données en utilisant cette méthode avec l'URI que vous avez placé dans le presse-papiers. Pour permettre la copie, faites en sorte que cette méthode détecte les URI contenant un chemin d'accès de copie spécial. Votre application peut ensuite créer un URI de copie à placer dans le presse-papiers, contenant le chemin de copie et un pointeur vers l'enregistrement exact que vous souhaitez copier.
getType()
Cette méthode doit renvoyer les types MIME des données que vous souhaitez copier. La méthode newUri() appelle getType() pour placer les types MIME dans le nouvel objet ClipData.

Les types MIME pour les données complexes sont décrits dans la section Fournisseurs de contenu.

Vous n'avez pas besoin d'utiliser les autres méthodes du fournisseur de contenu, telles que insert() ou update(). Une application de collage n'a besoin que d'obtenir les types MIME compatibles et de copier les données à partir de votre fournisseur. Si vous disposez déjà de ces méthodes, elles n'interfèrent pas avec les opérations de copie.

Les extraits de code suivants montrent comment configurer votre application pour copier des données complexes:

  1. Dans les constantes globales de votre application, déclarez une chaîne d'URI de base et un chemin d'accès qui identifie les chaînes d'URI que vous utilisez pour copier les données. Déclarez également un type MIME pour les données copiées.

    Kotlin

    // Declares the base URI string.
    private const val CONTACTS = "content://com.example.contacts"
    
    // Declares a path string for URIs that you use to copy data.
    private const val COPY_PATH = "/copy"
    
    // Declares a MIME type for the copied data.
    const val MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"
    

    Java

    // Declares the base URI string.
    private static final String CONTACTS = "content://com.example.contacts";
    
    // Declares a path string for URIs that you use to copy data.
    private static final String COPY_PATH = "/copy";
    
    // Declares a MIME type for the copied data.
    public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact";
    
  2. Dans l'activité à partir de laquelle les utilisateurs copient des données, configurez le code permettant de copier les données dans le presse-papiers. En réponse à une requête de copie, placez l'URI dans le presse-papiers.

    Kotlin

    class MyCopyActivity : Activity() {
        ...
    when(item.itemId) {
        R.id.menu_copy -> { // The user has selected a name and is requesting a copy.
            // Appends the last name to the base URI.
            // The name is stored in "lastName".
            uriString = "$CONTACTS$COPY_PATH/$lastName"
    
            // Parses the string into a URI.
            val copyUri: Uri? = Uri.parse(uriString)
    
            // Gets a handle to the clipboard service.
            val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    
            val clip: ClipData = ClipData.newUri(contentResolver, "URI", copyUri)
    
            // Sets the clipboard's primary clip.
            clipboard.setPrimaryClip(clip)
        }
    }
    

    Java

    public class MyCopyActivity extends Activity {
        ...
    // The user has selected a name and is requesting a copy.
    case R.id.menu_copy:
    
        // Appends the last name to the base URI.
        // The name is stored in "lastName".
        uriString = CONTACTS + COPY_PATH + "/" + lastName;
    
        // Parses the string into a URI.
        Uri copyUri = Uri.parse(uriString);
    
        // Gets a handle to the clipboard service.
        ClipboardManager clipboard = (ClipboardManager)
            getSystemService(Context.CLIPBOARD_SERVICE);
    
        ClipData clip = ClipData.newUri(getContentResolver(), "URI", copyUri);
    
        // Sets the clipboard's primary clip.
        clipboard.setPrimaryClip(clip);
    
  3. Dans le champ d'application global de votre fournisseur de contenu, créez un outil de mise en correspondance des URI et ajoutez un modèle d'URI correspondant aux URI que vous avez placés dans le presse-papiers.

    Kotlin

    // A Uri Match object that simplifies matching content URIs to patterns.
    private val sUriMatcher = UriMatcher(UriMatcher.NO_MATCH).apply {
    
        // Adds a matcher for the content URI. It matches.
        // "content://com.example.contacts/copy/*"
        addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT)
    }
    
    // An integer to use in switching based on the incoming URI pattern.
    private const val GET_SINGLE_CONTACT = 0
    ...
    class MyCopyProvider : ContentProvider() {
        ...
    }
    

    Java

    public class MyCopyProvider extends ContentProvider {
        ...
    // A Uri Match object that simplifies matching content URIs to patterns.
    private static final UriMatcher sURIMatcher = new UriMatcher(UriMatcher.NO_MATCH);
    
    // An integer to use in switching based on the incoming URI pattern.
    private static final int GET_SINGLE_CONTACT = 0;
    ...
    // Adds a matcher for the content URI. It matches
    // "content://com.example.contacts/copy/*"
    sUriMatcher.addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT);
    
  4. Configurez la méthode query(). Cette méthode peut gérer différents formats d'URI, selon la manière dont vous le codez, mais seul le modèle de l'opération de copie du presse-papiers s'affiche.

    Kotlin

    // Sets up your provider's query() method.
    override fun query(
            uri: Uri,
            projection: Array<out String>?,
            selection: String?,
            selectionArgs: Array<out String>?,
            sortOrder: String?
    ): Cursor? {
        ...
        // When based on the incoming content URI:
        when(sUriMatcher.match(uri)) {
    
            GET_SINGLE_CONTACT -> {
    
                // Queries and returns the contact for the requested name. Decodes
                // the incoming URI, queries the data model based on the last name,
                // and returns the result as a Cursor.
            }
        }
        ...
    }
    

    Java

    // Sets up your provider's query() method.
    public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
        String sortOrder) {
        ...
        // Switch based on the incoming content URI.
        switch (sUriMatcher.match(uri)) {
    
        case GET_SINGLE_CONTACT:
    
            // Queries and returns the contact for the requested name. Decodes the
            // incoming URI, queries the data model based on the last name, and
            // returns the result as a Cursor.
        ...
    }
    
  5. Configurez la méthode getType() afin de renvoyer un type MIME approprié pour les données copiées:

    Kotlin

    // Sets up your provider's getType() method.
    override fun getType(uri: Uri): String? {
        ...
        return when(sUriMatcher.match(uri)) {
            GET_SINGLE_CONTACT -> MIME_TYPE_CONTACT
            ...
        }
    }
    

    Java

    // Sets up your provider's getType() method.
    public String getType(Uri uri) {
        ...
        switch (sUriMatcher.match(uri)) {
        case GET_SINGLE_CONTACT:
            return (MIME_TYPE_CONTACT);
        ...
        }
    }
    

La section Coller les données d'un URI de contenu explique comment obtenir un URI de contenu à partir du presse-papiers, et l'utiliser pour obtenir et coller des données.

Copier des flux de données

Vous pouvez copier et coller de grandes quantités de texte et de données binaires sous forme de flux. Les données peuvent prendre différentes formes, par exemple:

  • Fichiers stockés sur l'appareil réel
  • Flux à partir de sockets
  • De grandes quantités de données sont stockées dans le système de base de données sous-jacent d'un fournisseur

Un fournisseur de contenu pour les flux de données permet d'accéder à ses données avec un objet descripteur de fichier, tel que AssetFileDescriptor, au lieu d'un objet Cursor. L'application de collage lit le flux de données à l'aide de ce descripteur de fichier.

Pour configurer votre application afin de copier un flux de données auprès d'un fournisseur, procédez comme suit:

  1. Configurez un URI de contenu pour le flux de données que vous placez dans le presse-papiers. Pour ce faire, vous pouvez procéder comme suit :
    • Encodez un identifiant pour le flux de données dans l'URI, comme décrit dans la section Encoder un identifiant sur l'URI, puis gérez dans votre fournisseur une table contenant les identifiants et le nom de flux correspondant.
    • Encodez le nom du flux directement sur l'URI.
    • Utilisez un URI unique qui renvoie toujours le flux actuel du fournisseur. Si vous utilisez cette option, n'oubliez pas de modifier votre fournisseur pour qu'il pointe vers un autre flux chaque fois que vous copiez le flux dans le presse-papiers à l'aide de l'URI.
  2. Indiquez un type MIME pour chaque type de flux de données que vous prévoyez de proposer. Les applications collées ont besoin de ces informations pour déterminer si elles peuvent coller les données dans le presse-papiers.
  3. Implémentez l'une des méthodes ContentProvider qui renvoient un descripteur de fichier pour un flux. Si vous encodez des identifiants sur l'URI de contenu, utilisez cette méthode pour déterminer le flux à ouvrir.
  4. Pour copier le flux de données dans le presse-papiers, créez l'URI de contenu et placez-le dans le presse-papiers.

Pour coller un flux de données, une application récupère l'extrait du presse-papiers, obtient l'URI et l'utilise dans un appel à une méthode de descripteur de fichier ContentResolver qui ouvre le flux. La méthode ContentResolver appelle la méthode ContentProvider correspondante, en lui transmettant l'URI de contenu. Votre fournisseur renvoie le descripteur de fichier à la méthode ContentResolver. L'application de collage est ensuite chargée de lire les données du flux.

La liste suivante présente les méthodes de descripteur de fichier les plus importantes pour un fournisseur de contenu. Chacun de ces éléments est associé à une méthode ContentResolver, avec la chaîne "Descripteur" ajoutée au nom de la méthode. Par exemple, l'analogique ContentResolver de openAssetFile() est openAssetFileDescriptor().

openTypedAssetFile()

Cette méthode renvoie un descripteur de fichier d'éléments, mais uniquement si le type MIME fourni est compatible avec le fournisseur. L'appelant (l'application qui effectue le collage) fournit un modèle de type MIME. Le fournisseur de contenu de l'application qui copie un URI dans le presse-papiers renvoie un handle de fichier AssetFileDescriptor s'il peut fournir ce type MIME et génère une exception dans le cas contraire.

Cette méthode gère les sous-sections de fichiers. Elle vous permet de lire les éléments que le fournisseur de contenu a copiés dans le presse-papiers.

openAssetFile()
Cette méthode est une forme plus générale de openTypedAssetFile(). Il ne filtre pas les types MIME autorisés, mais peut lire les sous-sections de fichiers.
openFile()
Il s'agit d'une forme plus générale de openAssetFile(). Il ne peut pas lire les sous-sections de fichiers.

Vous pouvez éventuellement utiliser la méthode openPipeHelper() avec votre méthode de descripteur de fichier. Cela permet à l'application de collage de lire les données de flux dans un thread d'arrière-plan à l'aide d'un pipe. Pour utiliser cette méthode, implémentez l'interface ContentProvider.PipeDataWriter.

Concevoir une fonctionnalité de copier-coller efficace

Pour concevoir une fonctionnalité de copier-coller efficace pour votre application, tenez compte des points suivants:

  • Le presse-papiers ne contient qu'un seul extrait à tout moment. Une nouvelle opération de copie effectuée par n'importe quelle application du système écrase l'extrait précédent. Étant donné que l'utilisateur peut quitter votre application et effectuer une copie avant de revenir, vous ne pouvez pas supposer que le presse-papiers contient l'extrait que l'utilisateur a précédemment copié dans votre application.
  • L'objectif de plusieurs objets ClipData.Item par extrait est de permettre le copier-coller de plusieurs sélections plutôt que différentes formes de référence à une sélection unique. Vous souhaitez généralement que tous les objets ClipData.Item d'un extrait aient la même forme. Autrement dit, ils doivent tous être du texte simple, un URI de contenu ou Intent, et non mixtes.
  • Lorsque vous fournissez des données, vous pouvez proposer différentes représentations MIME. Ajoutez les types MIME compatibles au ClipDescription, puis implémentez-les dans votre fournisseur de contenu.
  • Lorsque vous obtenez des données du presse-papiers, votre application doit vérifier les types MIME disponibles, puis décider de celui à utiliser, le cas échéant. Même si le presse-papiers contient un extrait et que l'utilisateur demande à le coller, l'application n'est pas obligée de le coller. Effectuez le collage si le type MIME est compatible. Vous pouvez forcer les données du presse-papiers en texte à l'aide de coerceToText(). Si votre application est compatible avec plusieurs types MIME disponibles, vous pouvez laisser l'utilisateur choisir celui qu'il souhaite utiliser.