Guida introduttiva: Condivisione di contenuto (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 ]

Le app più riuscite sono quelle che consentono agli utenti di condividere facilmente le attività con parenti e amici. Le app che facilitano agli utenti la condivisione di contenuti aumentano la propria visibilità, incoraggiando gli utenti a usarle più spesso.

Per imparare a usare queste API, prosegui nella lettura. Se sei più interessato ad apprendere in che modo la tua app può ricevere contenuto condiviso, vedi Guida introduttiva: Ricezione di contenuto condiviso.

Obiettivo: La lettura di questa guida introduttiva dovrebbe darti un'idea chiara di come condividere contenuto.

Prerequisiti

Occorre avere già familiarità con Visual Studio e i relativi modelli.
Occorre avere già familiarità con lo sviluppo in HTML e JavaScript.

Istruzioni

Scelta dei formati di dati

Alla base delle operazioni di condivisione vi è l'oggetto DataPackage. Questo oggetto contiene i dati che l'utente vuole condividere. I tipi di contenuto che un oggetto DataPackage può contenere includono:

Testo normale
Uniform Resource Identifier (URI)
HTML
Testo formattato
Bitmap
File
Dati definiti dallo sviluppatore

Un oggetto DataPackage può contenere uno o più di questi formati, in qualsiasi combinazione. Inoltre, un oggetto DataPackage può contenere un delegato, una funzione che viene chiamata quando l'app ricevente richiede i dati. Ti consigliamo di usare un delegato quando i dati che l'utente vuole condividere usano molte risorse. Un delegato, infatti, consente alle app di condividere i dati in modo più efficiente.

Scelta delle proprietà

Al momento della creazione del pacchetto di dati da condividere, hai la possibilità di fornire una varietà di proprietà che offrono ulteriori informazioni sul contenuto che stai per condividere. Queste proprietà contribuiscono a migliorare l'esperienza utente delle app di destinazione. Ad esempio, fornire un titolo e una descrizione che diano un'idea di ciò che l'utente sta condividendo può essere utile nelle situazioni in cui l'utente condivide contenuti con più app. L'aggiunta di un'anteprima alla condivisione di un'immagine o di un link a una pagina Web può invece fornire un riferimento visivo all'utente. Per ulteriori informazioni sulle proprietà disponibili, consulta la nostra documentazione su DataPackage.DataPackagePropertySet.

Impostazione dell'origine di condivisione

Per impostare la tua applicazione come app di origine di condivisione, devi innanzitutto recuperare l'istanza della classe DataTransferManager che è stata assegnata alla finestra corrente.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();

Questa classe supporta un evento DataRequested, che viene attivato quando l'utente vuole richiamare la condivisione. In un'app di Windows Store questa operazione viene eseguita automaticamente quando l'utente richiama l'accesso alla condivisione. Se stai sviluppando un'app per Windows Phone, non esiste alcun accesso alla condivisione incorporato. Dovrai quindi aggiungere un controllo che l'utente dovrà toccare per attivare il gestore.

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

L'esempio di sopra registra un gestore eventi che viene chiamato ogni volta che viene attivato un evento datarequested. Il gestore riceve un oggetto DataRequest, che viene usato dall'app per impostare i dati che l'utente vuole condividere dall'app di origine della condivisione.

Qualsiasi contenuto condiviso deve contenere due proprietà: un titolo e il contenuto stesso. È inoltre consigliabile includere una proprietà di descrizione per maggiore chiarezza.

Il codice seguente si basa sugli esempi precedenti e mostra come condividere testo semplice con un'app di destinazione.

function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Text Example";
    request.data.properties.description = "Demonstrates how to share text.";
    request.data.setText("Hello World!");
}

Condivisione e delegati

Talvolta non è il caso di preparare i dati immediatamente, quando l'utente richiama la condivisione. Ad esempio, se la tua app supporta diversi formati di dati, non sarebbe pratico creare tutti i formati immediatamente. È meglio aspettare che l'app di destinazione specifichi il formato desiderato e, a quel punto, generare i dati richiesti. A questo scopo, devi configurare l'oggetto DataPackage in modo che si popoli solo dei dati necessari tramite una chiamata su richiesta al delegato.

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

Per maggiori dettagli su questa forma di condivisione, vedi Come condividere file.

Richiamo del riquadro di condivisione a livello di programmazione

Dopo che hai impostato il contenuto per la condivisione, puoi inviarlo all'utente. Per ricevere il contenuto, l'utente non deve fare altro che selezionare l'app. Per le situazioni in cui l'uso del pulsante di accesso rapido non è la scelta ideale, ad esempio per la condivisione di un punteggio alto in un gioco, puoi avviare il pulsante di accesso rapido Condividi a livello di programmazione.

Nota

Poiché la Charms bar non esiste in Windows Phone 8.1, devi includere l'opzione di condivisione a livello di programmazione. Può essere resa sempre accessibile come parte della barra di un'app oppure associata a un controllo specifico in una determinata pagina.

function showShareUI() {
    Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
}

Gestione di errori e altri problemi

Nella maggior parte dei casi, fornire contenuto è semplice. Vi sono tuttavia situazioni nelle quali la tua app potrebbe non essere in condizione di condividere. Per aiutarti a gestire queste situazioni, in Windows 8.1, l'oggetto DataRequest supporta un metodo FailWithDisplayText. Usa questo metodo per visualizzare un messaggio di testo se l'utente non può condividere da una particolare vista o se deve eseguire ulteriori passaggi per poter condividere. Ad esempio, l'app potrebbe richiedere all'utente di selezionare il contenuto da condividere, ma l'utente non seleziona alcun contenuto.

Riepilogo e passaggi successivi

A questo punto dovresti avere le idee chiare su come funziona la condivisione.

Per saperne di più o per esempi specifici su come aggiungere la condivisione alla tua app, vedi:

Argomenti correlati

Scelta dei formati di dati per la condivisione

Linee guida ed elenco di controllo per la condivisione di contenuto

Guida introduttiva: Ricezione di contenuto condiviso