Démarrage rapide : réception de contenu partagé (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Ce démarrage rapide vous guide à travers les étapes nécessaires pour que votre application puisse recevoir du contenu partagé d’une autre application.

Objectif: découvrir le processus de réception du contenu partagé.

Prérequis

Pour utiliser le code décrit dans cette section :

Vous devez être familiarisé avec Visual Studio et ses modèles connexes.
Vous devez être familiarisé avec JavaScript.

Instructions

1. Prise en charge du contrat de partage

Avant que votre application puisse recevoir un contenu partagé, vous devez déclarer qu’elle prend en charge le contrat de partage. Ce contrat indique au système que votre application est apte à recevoir du contenu. Si vous utilisez un modèle Visual Studio pour créer votre application, voici comment prendre en charge le contrat de partage :

Ouvrez le fichier manifeste. Il doit normalement s’appeler package.appxmanifest.
Ouvrez l’onglet Déclarations.
Choisissez Partage cible dans la liste Déclarations disponibles.

Pour en savoir plus, voir Modèle d’élément de contrat de cible de partage.

2. Spécification des types de fichiers et formats de données à prendre en charge

En tant que développeur de l’application cible, vous devez déterminer pour quels types de fichiers et formats de données vous souhaitez fournir une prise en charge. Pour spécifier les types de fichiers à prendre en charge :

Ouvrez le fichier manifeste.
Dans la section Types de fichiers pris en charge de la page Déclarations, cliquez sur Ajouter nouveau.
Tapez l’extension de nom de fichier associée au type de fichiers à prendre en charge. Par exemple, .docx. Vous devez inclure le point (.).

Pour prendre en charge tous les types de fichiers, activez la case à cocher Prend en charge tout type de fichier.

Pour spécifier les formats de données à prendre en charge :

Ouvrez le fichier manifeste.
Dans la section Formats de données, cliquez sur Ajouter.
Tapez le nom du format de données à prendre en charge. Par exemple, "Texte".

Les API de partage prennent en charge plusieurs formats standard, parmi lesquels les formats texte, HTML et bitmap. Vous pouvez également spécifier des types de fichiers et formats de données personnalisés. Dans ce cas, souvenez-vous que les applications sources doivent savoir ce que sont ces types et formats ; sans cela ces applications ne partageront pas les données de ce type.

3. Gestion de l’activation du partage

Lorsqu’un utilisateur sélectionne votre application, un événement activated d’application est déclenché. Votre application doit gérer cet événement afin de traiter les données que l’utilisateur veut partager. Un événement activated peut être déclenché pour de multiples raisons. Vous devez donc d’abord vérifier s’il a été déclenché en vue d’un partage de données.

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
    // Code to handle activation goes here.
}

Les données que l’utilisateur souhaite partager sont stockées dans un objet ShareOperation. Vous pouvez utiliser cet objet pour vérifier le format des données qu’il contient. Voici l’exemple d’un gestionnaire d’événements qui gère du contenu partagé au format texte brut :

var shareOperation = eventObject.detail.shareOperation;
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    shareOperation.data.getTextAsync().done(function (text) {
            // To output the text using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            document.getElementById("output").innerText = text;
        }, function (e) {
            displayError("Error retrieving Text format: " + e);
        }
    });
}

4. Notification sur l’état du partage étendu (pour les opérations plus longues)

Remarque

L’étape suivante ne concerne que les applications du Windows Store. Vous pouvez appeler les méthodes de rapport ci-après à partir de Windows Phone 8.1, mais toutes les données ne seront pas retournées.

Dans certains cas, votre application peut avoir besoin de plus de temps pour traiter les données que l’utilisateur souhaite partager. C’est ce que nous appelons des partages étendus Il s’agit, par exemple, des partages de collections de fichiers ou d’images. Ces éléments sont plus volumineux qu’une simple chaîne de texte, ce qui explique leur temps de traitement plus long.

Remarque Si votre application ne peut que recevoir des éléments simples, tels que du texte ou des liens hypertexte, vous pouvez ignorer cette section.

En tant qu’application cible, votre application ne doit pas obliger l’utilisateur à regarder l’interface utilisateur de votre application juste parce qu’il lui faut plus de temps pour traiter les données. Pour éviter cela, utilisez l’objet ShareOperation afin qu’il notifie au système que votre application n’a pas terminé l’opération de partage en cours. L’utilisateur peut ainsi masquer l’interface utilisateur de votre application et poursuivre ses autres tâches. Pendant ce temps, votre application continue le traitement des données en arrière-plan.

shareOperation.reportStarted();

Après l’appel de la méthode reportStarted, ne prévoyez aucune interaction avec votre application de la part de l’utilisateur. Par conséquent, vous ne devez appeler cette méthode que si votre application est parvenue à un stade de l’opération où elle peut être masquée par l’utilisateur.

Avec un partage étendu, l’utilisateur peut être amené à masquer l’application source avant que votre application n’ait reçu toutes les données de l’objet DataPackage. Pour cette raison, nous recommandons que votre application avertisse le système quand elle a obtenu toutes les données nécessaires. Cela permet au système de suspendre ou d’arrêter l’application source selon les besoins.

shareOperation.reportDataRetreived();

Vous pouvez également appeler reportError pour envoyer un message d’erreur au système en cas de problème. L’utilisateur voit le message quand il vérifie l’état du partage. Dès que vous appelez reportError, votre application est arrêtée et le partage est terminé— l’utilisateur devra tout recommencer pour partager le même contenu dans votre application. Selon la situation, vous pouvez décider qu’un certain type d’erreur ne suffit pas pour mettre fin à l’opération de partage. Dans ce cas, vous pouvez omettre d’appeler reportError et continuer le partage.

shareOperation.reportError("Could not reach the server! Try again later.");

Lorsque vous utilisez ces méthodes, vous les appelez généralement selon l’ordre indiqué, une seule fois chacune. Toutefois, certaines fois une application cible peut appeler reportDataRetrieved avant reportStarted. Par exemple, l’application peut récupérer les données comme partie d’une tâche dans le gestionnaire d’activation, mais ne pas appeler reportStarted jusqu’à ce que l’utilisateur clique sur un bouton Partager.

Pour obtenir un exemple concret de ce type de partage, voir notre Exemple de partage de contenu cible entre applications.

5. Notification de la fin du partage

Enfin, lorsque votre application a fini de traiter le contenu partagé, appelez la méthode reportCompleted.

shareOperation.reportCompleted();

Une fois que votre application signale que le partage est terminé, elle est masquée.

6. Renvoi d’un objet Quicklink si le partage a réussi

Remarque

Les liens rapides ne sont pas pris en charge dans Windows Phone 8.1. Les applications du Windows Phone Store peuvent recevoir des liens rapides dans le cadre d’une opération de partage, mais ceux-ci sont automatiquement ignorés.

Quand un utilisateur sélectionne votre application pour recevoir du contenu partagé, nous vous recommandons de créer un objet QuickLink. Un objet QuickLink est une sorte de raccourci qui permet à l’utilisateur de partager plus facilement des informations avec votre application. Par exemple, votre application peut créer un objet QuickLink qui ouvre un nouveau message électronique dans lequel l’adresse de messagerie du destinataire est déjà indiquée.

Lorsqu’un utilisateur sélectionne votre application pour recevoir du contenu partagé, nous vous recommandons de créer un objet QuickLink. Un objet QuickLink est un raccourci qui permet à l’utilisateur de partager plus facilement des informations avec votre application. Par exemple, votre application peut créer un objet QuickLink qui ouvre un nouveau message électronique dans lequel l’adresse de messagerie du destinataire est déjà indiquée.

Un objet QuickLink doit comporter un titre, une icône et un identificateur. Le titre (par exemple, « Message pour maman ») et l’icône s’affichent lorsque l’utilisateur appuie sur l’icône Partager. L’identificateur est ce que votre application utilise pour identifier quel objet QuickLink a été choisi. Quand votre application crée un objet QuickLink, elle renvoie cet objet QuickLink au système en appelant la méthode reportCompleted de l’objet ShareOperation. Voici un exemple :

function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = id("quickLinkTitle").value;

    // For quicklinks, the supported FileTypes and DataFormats are set independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, dataFormats.bitmap, 
        dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

Souvenez-vous que votre application stocke l’identificateur de l’objet QuickLink ainsi que les données utilisateur correspondantes. Quand l’utilisateur appuie sur l’objet QuickLink, vous pouvez obtenir l’ID de ce dernier à l’aide de la propriété ShareOperation.quickLinkId. Lorsqu’un partage avec un objet QuickLink réussit, renvoyez le même objet QuickLink en appelant reportCompleted.

Récapitulatif et étapes suivantes

Vous avez désormais les connaissances de base sur le processus de réception du contenu partagé et sur la création d’un objet QuickLink permettant aux utilisateurs de partager plus facilement du contenu avec votre application.

Pour plus d’informations ou des exemples spécifiques illustrant l’ajout de fonctionnalités de partage à votre application, vous pouvez consulter les ressources suivantes :

Remarque Le débogage d’une application cible de partage est différent du débogage d’autres types d’applications. Pour en savoir plus, voir Recommandations pour le débogage des applications cibles.