Come ricevere codice HTML (HTML)

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Il contenuto HTML può essere costituito da contenuti diversi, tra cui testo, immagini e altre informazioni. Ecco come impostare l'app per ricevere il contenuto HTML che un utente vuole condividere.

Quando aggiungi questa funzionalità all'app, puoi anche scegliere di accettare contenuto in formato testo. Il testo è facilmente convertibile in HTML, pertanto aggiungendo il supporto per questo formato avrai la sicurezza che la tua app sarà disponibile per gli utenti più spesso. Per altre informazioni, vedi Come ricevere testo.

Cosa sapere

Tecnologie

Prerequisiti

Occorre avere già familiarità con Visual Studio e i modelli associati.
Occorre avere già familiarità con JavaScript.

Istruzioni

Passaggio 1: Supporto del contratto Condivisione

Per consentire all'app di ricevere contenuto condiviso, devi dichiarare che supporta il contratto Condivisione, grazie al quale il sistema sa che l'app è disponibile a ricevere contenuto. Se usi un modello di Microsoft Visual Studio per creare la tua app, ecco come puoi supportare il contratto Condivisione:

Apri il file manifesto. Dovrebbe avere un nome simile a package.appxmanifest.
Apri la scheda Dichiarazioni.
Scegli Condivisione destinazione dall'elenco Dichiarazioni disponibili.

Passaggio 2: Specificare che l'app supporta HTML

Per specificare che supporti HTML come formato dati:

Apri il file manifesto.
Nella sezione Formati dati fai clic su Aggiungi nuovo.
Digita html.

Nota Puoi specificare un diverso punto di ingresso quando la tua app è attivata per il contratto Condivisione destinazione. A questo scopo, modifica la voce del punto di ingresso della pagina Start nella sezione delle impostazioni App della dichiarazione Condivisione destinazione nel manifesto del pacchetto. Consigliamo vivamente di usare anche un file JavaScript separato per gestire l'attivazione di questa pagina. Per un approfondimento, vedi l'esempio di app di destinazione per la condivisione di contenuto.

Passaggio 3: Aggiungere un gestore eventi per rilevare quando viene attivata l'app

Il sistema attiva l'app quando un utente la seleziona per condividere il contenuto. Poiché l'app può essere attivata in svariati modi, devi aggiungere codice al gestore per l'evento activated per rilevare il motivo dell'attivazione. Per farlo, controlla il valore della proprietà kind.

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched. Initialize as appropriate.
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        ...
    }
};

Se usi una pagina di avvio dedicata per il contratto Condivisione destinazione, puoi evitare di controllare la proprietà kind.

Passaggio 4: Recuperare l'oggetto ShareOperation

L'oggetto ShareOperation contiene tutti i dati necessari per consentire all'app di recuperare il contenuto che un utente vuole condividere.

shareOperation = args.detail.shareOperation;

Passaggio 5: Ritornare rapidamente dal gestore eventi attivato.

Il gestore eventi activated deve ritornare rapidamente. Aggiungere in coda un evento asincrono dal gestore eventi activated, di modo che l'elaborazione dei dati condivisi avvenga al ritorno del gestore eventi.

WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });

I passaggi rimanenti implementano la funzione shareReady.

Passaggio 6: Verificare se DataPackageView contiene codice HTML

L'oggetto ShareOperation contiene un oggetto DataPackageView. Questo oggetto è di fatto una versione di sola lettura dell'oggetto DataPackage usato dall'app di origine per creare i dati. Usa questo oggetto per verificare se il contenuto da condividere è disponibile in formato HTML.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.html)) {
    // Code to get HTML goes here.
}

È buona regola controllare che il DataPackage contenga il formato di dati in cui sei interessato, anche se la tua app supporta solo un formato. In tal modo sarà più semplice in seguito supportare altri tipi e formati di dati e formati di file.

Passaggio 7: Elaborare il contenuto HTML

Per recuperare il contenuto HTML, chiama il metodo getHtmlFormatAsync. Questo metodo restituisce il contenuto HTML nella specifica HTML Format. Puoi usare DataTransfer.HtmlFormatHelper.getStaticFragment per estrarre il frammento di codice HTML da HTML Format. Il frammento così ottenuto viene inoltre ripulito, in modo da rimuovere qualsiasi contenuto dinamico (ad esempio, i tag di script) e garantire la sicurezza del rendering nell'applicazione.

shareOperation.data.getHtmlFormatAsync().then(function (htmlFormat) {
    var htmlFragment = Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.getStaticFragment(htmlFormat);
    // In this example, we only display the HTML. To do this, you need 
    // a <div> element with an id of "output" in your HTML page.

    // In your app, replace this with whatever is appropriate for your scenario.
    document.getElementById("output").innerHTML = htmlFragment;
});

Naturalmente l'operazione da eseguire sul contenuto HTML dipende dall'app.

Passaggio 8: Risolvere tutti i riferimenti alle immagini per l'HTML.

L'app di origine di condivisione potrebbe includere nel codice HTML immagini che si trovano nel contesto di archiviazione locale (ad esempio, ms-appx, ms-appdata e così via). In questo caso, l'app di origine dovrebbe aver popolato la mappa delle risorse con i riferimenti opportuni, in modo da consentire alla destinazione di condivisione di accedere a queste risorse.

Per risolvere le immagini locali dall'app di origine, usa la proprietà resourceMap per cercare il riferimento a ogni immagine e ottenere il corrispondente RandomAccessStreamReference. L'esempio seguente consente di creare l'oggetto URI (Uniform Resource Identifier) per eseguire il rendering delle immagini nel codice HTML. Nella tua app sostituisci questo codice con tutte le modifiche opportune per lo scenario specifico.

var images = document.getElementById("output").getElementsByTagName("img");
if (images.length > 0) {
    shareOperation.data.getResourceMapAsync().done(function (resourceMap) {
        if (resourceMap.size > 0) {
            for (var i = 0, len = images.length; i < len; i++) {
                var streamReference = resourceMap[images[i].getAttribute("src")];
                if (streamReference) {
                    // Call a helper function to map the image element's src to a 
                    // corresponding blob URL generated from the streamReference.
                    setResourceMapURL(streamReference, images[i]);
                }
            }
        }
    });
}

Passaggio 9: Chiamare reportCompleted

Dopo che l'app ha finito di condividere il contenuto, chiama reportCompleted. Dopo aver chiamato questo metodo, il sistema chiude l'app.

shareOperation.reportCompleted();

Osservazioni

Per vedere l'intera esperienza end-to-end di un'app che riceve un'immagine come parte della condivisione, esamina il codice dell'esempio di app di destinazione per la condivisione di contenuto.

Esempio completo

var shareOperation = null;

function setResourceMapURL(streamReference, imageElement) {
    if (streamReference) {
        streamReference.openReadAsync().done(function (imageStream) {
            if (imageStream) {
                var url = URL.createObjectURL(imageStream, { oneTimeOnly: true });
                imageElement.src = url;
            }
        }, function (e) {
            imageElement.alt = "Failed to load";
        });
    }
}

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.html)) {
        shareOperation.data.getHtmlFormatAsync().then(function (htmlFormat) {
            var htmlFragment = Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.getStaticFragment(htmlFormat);
            // In this example, we only display the HTML. To do this, you need 
            // a <div> element with an id of "output" in your HTML page.
            // In your app, replace this with whatever is appropriate for your scenario.
            document.getElementById("output").innerHTML = htmlFragment;

            // Now we loop through any images and use the resourceMap to map each
            // image element's src.
            var images = document.getElementById("output").getElementsByTagName("img");

            if (images.length > 0) {
                shareOperation.data.getResourceMapAsync().done(function (resourceMap) {
                    if (resourceMap.size > 0) {
                        for (var i = 0, len = images.length; i < len; i++) {
                            var streamReference = resourceMap[images[i].getAttribute("src")];
                                if (streamReference) {
                                    // Call a helper function to map the image element's
                                    // src to a corresponding blob URL generated from the
                                    // streamReference.
                                    setResourceMapURL(streamReference, images[i]);
                                }
                        }
                    }
                });
            }
        });
    } 
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched.
        args.setPromise(WinJS.UI.processAll());
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        // This application has been activated for the Share contract
        args.setPromise(WinJS.UI.processAll());

        // We receive the ShareOperation object as part of the eventArgs.
        shareOperation = args.detail.shareOperation;

        // We queue an asychronous event so that working with the ShareOperation 
        // object does not block or delay the return of the activation handler.
        WinJS.Application.addEventListener("shareready", shareReady, false);
        WinJS.Application.queueEvent({ type: "shareready" });
    }
};