Partager des donnéesShare data

Cet article explique comment prendre en charge le contrat de partage dans une application de plateforme Windows universelle (UWP).This article explains how to support the Share contract in a Universal Windows Platform (UWP) app. Le contrat de partage constitue un moyen simple pour partager rapidement des données, telles que du texte, des liens, des photos et vidéos, entre les applications.The Share contract is an easy way to quickly share data, such as text, links, photos, and videos, between apps. Par exemple, un utilisateur peut partager une page web avec ses amis à l’aide d’une application de réseau social ou enregistrer un lien dans une application de prise de notes pour s’y référer plus tard.For example, a user might want to share a webpage with their friends using a social networking app, or save a link in a notes app to refer to later.

Notes

Les exemples de code de cet article sont écrits pour les applications UWP.The code examples in this article are written for UWP apps. Les applications de bureau WPF, Windows Forms et C++/Win32 doivent utiliser l’interface IDataTransferManagerInterop pour obtenir l’objet DataTransferManager pour une fenêtre spécifique.WPF, Windows Forms, and C++/Win32 desktop apps must use the IDataTransferManagerInterop interface to get the DataTransferManager object for a specific window. Pour plus d’informations, consultez l’exemple ShareSource .For more information, see the ShareSource sample.

Configurer un gestionnaire d’événementsSet up an event handler

Ajoutez un gestionnaire d’événements DataRequested à appeler chaque fois qu’un utilisateur appelle share.Add a DataRequested event handler to be called whenever a user invokes share. Cela peut se produire lorsque l’utilisateur appuie sur un contrôle dans votre application (par exemple, une commande de barre d’application ou un bouton) ou automatiquement dans un scénario spécifique (par exemple, si l’utilisateur a terminé un niveau et obtient un score élevé).This can occur either when the user taps a control in your app (such as a button or app bar command) or automatically in a specific scenario (if the user finishes a level and gets a high score, for example).

DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();
dataTransferManager.DataRequested += DataTransferManager_DataRequested;

Lorsqu’un événement DataRequested survient, votre application reçoit un objet DataRequest.When a DataRequested event occurs, your app receives a DataRequest object. Cet objet contient une classe DataPackage que vous pouvez utiliser pour fournir le contenu qu’un utilisateur souhaite partager.This contains a DataPackage that you can use to provide the content that the user wants to share. Vous devez fournir un titre et des données à partager.You must provide a title and data to share. La description est facultative, mais recommandée.A description is optional, but recommended.

DataRequest request = args.Request;

Choisir les donnéesChoose data

Vous pouvez partager différents types de données, notamment :You can share various types of data, including:

  • Texte brutPlain text
  • URI (Uniform Resource Identifiers)Uniform Resource Identifiers (URIs)
  • HTMLHTML
  • Texte mis en formeFormatted text
  • Images bitmapBitmaps
  • FichiersFiles
  • Données personnalisées définies par le développeurCustom developer-defined data

L’objet DataPackage peut contenir un ou plusieurs de ces formats, dans n’importe quelle combinaison.The DataPackage object can contain one or more of these formats, in any combination. L’exemple suivant illustre le partage de texte.The following example demonstrates sharing text.

request.Data.SetText("Hello world!");

Définir des propriétésSet properties

Lorsque vous créez un package de données en vue de le partager, vous pouvez définir diverses propriétés qui fournissent des informations supplémentaires sur le contenu partagé.When you package data for sharing, you can supply a variety of properties that provide additional information about the content being shared. Ces propriétés aident les applications cibles à améliorer l’expérience utilisateur.These properties help target apps improve the user experience. Par exemple, une description se révèle utile lorsque l’utilisateur partage du contenu avec plusieurs applications.For example, a description helps when the user is sharing content with more than one app. De même, un lien vers une page web ou une miniature ajoutée à une image partagée servent de référence visuelle à l’utilisateur.Adding a thumbnail when sharing an image or a link to a web page provides a visual reference to the user. Pour plus d’informations, consultez DataPackagePropertySet.For more information, see DataPackagePropertySet.

Toutes les propriétés sont facultatives, à l’exception du titre.All properties except the title are optional. La propriété title est obligatoire et doit être définie.The title property is mandatory and must be set.

request.Data.Properties.Title = "Share Example";
request.Data.Properties.Description = "A demonstration on how to share";

Lancer l’interface utilisateur de partageLaunch the share UI

Une interface utilisateur pour le partage est fournie par le système.A UI for sharing is provided by the system. Pour le lancer, appelez la méthode ShowShareUI .To launch it, call the ShowShareUI method.

DataTransferManager.ShowShareUI();

Gérer les erreursHandle errors

Dans la plupart des cas, le partage de contenu est un processus simple.In most cases, sharing content is a straightforward process. Toutefois, un élément inattendu peut toujours se produire.However, there's always a chance that something unexpected could happen. Par exemple, l’application peut avoir besoin que l’utilisateur sélectionne du contenu à partager alors que l’utilisateur ne l’a pas fait.For example, the app might require the user to select content for sharing but the user didn't select any. Pour gérer ces situations, utilisez la méthode FailWithDisplayText, qui affiche un message destiné à l’utilisateur en cas de problème.To handle these situations, use the FailWithDisplayText method, which will display a message to the user if something goes wrong.

Retarder le partage avec les déléguésDelay share with delegates

Parfois, il est dénué de sens de préparer les données que l’utilisateur veut partager sur le champ.Sometimes, it might not make sense to prepare the data that the user wants to share right away. Par exemple, si votre application prend en charge l’envoi d’un fichier image de grande taille dans différents formats possibles, il n’est pas efficace de créer toutes ces images avant que l’utilisateur effectue sa sélection.For example, if your app supports sending a large image file in several different possible formats, it's inefficient to create all those images before the user makes their selection.

Pour résoudre ce problème, un DataPackage peut contenir un délégué (fonction appelée lorsque l’application réceptrice demande des données).To solve this problem, a DataPackage can contain a delegate — a function that is called when the receiving app requests data. Nous vous recommandons d’utiliser un délégué chaque fois que les données que souhaite partager un utilisateur font appel à des ressources importantes.We recommend using a delegate any time that the data a user wants to share is resource-intensive.

async void OnDeferredImageRequestedHandler(DataProviderRequest request)
{
    // Provide updated bitmap data using delayed rendering
    if (this.imageStream != null)
    {
        DataProviderDeferral deferral = request.GetDeferral();
        InMemoryRandomAccessStream inMemoryStream = new InMemoryRandomAccessStream();

        // Decode the image.
        BitmapDecoder imageDecoder = await BitmapDecoder.CreateAsync(this.imageStream);

        // Re-encode the image at 50% width and height.
        BitmapEncoder imageEncoder = await BitmapEncoder.CreateForTranscodingAsync(inMemoryStream, imageDecoder);
        imageEncoder.BitmapTransform.ScaledWidth = (uint)(imageDecoder.OrientedPixelWidth * 0.5);
        imageEncoder.BitmapTransform.ScaledHeight = (uint)(imageDecoder.OrientedPixelHeight * 0.5);
        await imageEncoder.FlushAsync();

        request.SetData(RandomAccessStreamReference.CreateFromStream(inMemoryStream));
        deferral.Complete();
    }
}

Voir aussiSee also