Come ricevere testo (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 testo è forse il formato dati più comunemente condiviso dagli utenti. Oltre a essere la prima scelta per contenuti quali gli aggiornamenti di stato, è l'opzione consigliata per app che condividono link, HTML e altre informazioni.

Quando scrivi un'app di destinazione, in genere devi supportare il testo come parte della condivisione. In questo modo gli utenti potranno selezionare la tua app in numerose situazioni. Premesso questo, non supportare il formato testo se ritieni che possa solo confondere gli utenti. Se ad esempio la tua app server principalmente a gestire file, una rappresentazione dei file in formato testo non è quello che gli utenti si aspettano dall'app.

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 (package.appxmanifest).
Apri la scheda Dichiarazioni.
Scegli Condivisione destinazione dall'elenco Dichiarazioni disponibili.
Fai clic su Aggiungi per aggiungere il supporto del contratto Condivisione destinazione nella tua app.

Passaggio 2: Specificare che l'app supporta il testo

Quando scrivi un'app di destinazione, puoi specificare sia i tipi che i formati dei file. Per specificare i tipi di file supportati:

Apri il file manifesto.
Nella sezione Tipi file supportati fai clic su Aggiungi nuovo.
Digita .txt. Devi includere il punto (.). prima di txt e non quello dopo.

Per specificare che supporti il testo come formato dati:

Apri il file manifesto.
Nella sezione Formati dati fai clic su Aggiungi nuovo.
Digita "testo" (senza le virgolette).

I passaggi precedenti consentono di aggiungere al manifesto la sezione seguente:

<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <DataFormat>text</DataFormat>
    </ShareTarget>
  </Extension>
</Extensions>

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 il codice 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) {
        ...
    }
};

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 i dati condivisi contengono testo.

La proprietà shareOperation.data 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 testo.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    // Code to process text 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 formati di dati.

Passaggio 7: Elaborare il testo

Per recuperare il testo, chiama il metodo DataPackageView.getText.

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;
});

Naturalmente l'operazione da eseguire sul testo dipende dall'app.

Passaggio 8: Chiamare reportCompleted

Dopo che l'app ha finito di condividere correttamente 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 testo come parte della condivisione, esamina il codice dell'esempio di app di destinazione per la condivisione di contenuto.

var shareOperation = null;

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
        shareOperation.data.getTextAsync().done(function (textValue) {
            // 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 = textValue;
        });
    }
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched. Initialize as appropriate.
        args.setPromise(WinJS.UI.processAll());
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        // This app has been activated share.
        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" });
    }
};