Comment partager du contenu HTML (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 ]

Le partage de contenu HTML est différent du partage d’autres formats de base, tels que du texte ou un lien. La principale difficulté avec ce type de contenu est que le contenu sélectionné par l’utilisateur peut comporter des références à d’autres éléments. Lorsque vous créez une application qui prend en charge le partage de contenu HTML, vous devez réfléchir à la façon dont ces références doivent être gérées pour permettre aux utilisateurs de partager le contenu qu’ils souhaitent.

Le partage d’un contenu HTML combinant du texte et une image illustre bien cette problématique. Lorsqu’un utilisateur sélectionne ce type de contenu et appuie sur l’icône Partager, son intention est de partager simultanément le texte et l’image. Or, le contenu HTML ne stocke pas l’image, mais à la place, une balise img qui pointe vers l’emplacement de l’image. Vous devez configurer un mappage des ressources si la référence de l’image n’est pas accessible à une application cible, comme une image stockée localement.

Pour fournir une prise en charge du contenu HTML qui réponde aux attentes des utilisateurs, vous pouvez utiliser l’espace de noms Windows.ApplicationModel.DataTransfer. Celui-ci inclut quelques fonctions qui facilitent la capture des éléments référencés, tels que les images. Nous allons vous montrer comment faire.

Ce que vous devez savoir

Technologies

Windows.ApplicationModel.DataTransfer

Prérequis

Vous devez être familiarisé avec Visual Studio et ses modèles connexes.
Vous devez être familiarisé avec JavaScript.
Vous devez savoir utiliser JavaScript pour identifier le contenu HTML sélectionné par un utilisateur et trouver les instances des éléments enfants (telles que les balises img) au sein de cette sélection.

Instructions

Étape 1: Configurer votre application en tant que source de partage

L’objet DataTransferManager est le point de départ principal de toute opération de partage. Ajoutez un gestionnaire d’événements DataRequested qui se déclenche quand l’utilisateur souhaite appeler le partage. Dans une application du Windows Store, cela se produit automatiquement quand l’utilisateur appelle l’icône Partager. Si vous développez une application pour Windows Phone, aucune icône Partager n’est intégrée, donc vous devez ajouter un contrôle sur lequel l’utilisateur peut appuyer pour déclencher le gestionnaire.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareHtmlHandler);

Les étapes restantes servent à implémenter la fonction shareHtmlHandler.

Étape 2: obtenir un objet DataRequest

Lorsqu’un événement datarequested survient, votre application reçoit un objet DataRequest. Cet objet contient une classe DataPackage que vous pouvez utiliser pour fournir le contenu qu’un utilisateur souhaite partager.

var request = e.request;

Étape 3: Définir les propriétés de titre et de description

request.data.properties.title = "Share Html Example";
request.data.properties.description =
    "Demonstrates how to share an HTML fragment with a local image.";

Étape 4: utiliser la méthode createHtmlFormat pour mettre en forme le fragment

La fonction createHtmlFormat inclut dans le format HTML les en-têtes et autres informations dont le système a besoin pour partager le contenu.

var localImage = "ms-appx:///images/logo.png";
var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
var htmlFormat = 
    Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);

Étape 5: ajouter le contenu HTML à l’objet DataPackage

Pour ajouter le contenu HTML, utilisez la fonction setHtmlFormat.

request.data.setHtmlFormat(htmlFormat);

Étape 6: Créer un RandomAccessStreamReference de l’image locale

var streamRef = 
    Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));

Étape 7: Ajouter RandomAccessStreamReference au mappage de ressources

Pour ajouter le fichier image, utilisez la propriété resourceMap.

request.data.resourceMap[localImage] = streamRef;

Si le fragment HTML qui est en cours de partage contient des images locales, vous devrez répéter cette étape pour chacune d’elles.

Terminer l’exemple

Voici un exemple d’une fonction qui définit le contenu HTML qu’un utilisateur souhaite partager. Pour obtenir un exemple plus complet, voir l’exemple de notre bibliothèque de code.

function shareHtmlHandler(e) {
    var localImage = "ms-appx:///images/logo.png";
    var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
    var request = e.request;
    request.data.properties.title = "Share Html Example";
    request.data.properties.description = "Demonstrates how to share an HTML fragment with a local image.";
    var htmlFormat = Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);
    request.data.setHtmlFormat(htmlFormat);
    var streamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));
    request.data.resourceMap[localImage] = streamRef;
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app is newly launched; register the app as a share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", shareHtmlHandler);
        } else {
            // TODO: This app was reactivated from suspension.
            // Restore the app state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};