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

Questa guida introduttiva illustra quali passaggi eseguire per ricevere contenuto condiviso da un'altra app.

Obiettivo: imparare a ricevere contenuto condiviso.

Prerequisiti

Per usare il codice descritto in questa sezione:

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

Istruzioni

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 Visual Studio per creare la tua app, ecco come puoi supportare il contratto Condivisione:

Apri il file manifesto. Dovrebbe essere denominato package.appxmanifest.
Apri la scheda Dichiarazioni.
Scegli Condivisione destinazione dall'elenco Dichiarazioni disponibili.

Per altre informazioni, vedi Modello di elemento Contratto condivisione di destinazione.

2. Specifica dei tipi di file e dei formati di dati supportati

Come sviluppatore dell'app di destinazione, devi decidere quali tipi di file e formati di dati vuoi supportare. Per specificare i tipi di file supportati:

Apri il file manifesto.
Nella sezione Tipi file supportati della pagina Dichiarazioni fai clic su Aggiungi nuovo.
Digita l'estensione del nome di file che vuoi supportare, ad esempio .docx. Ricorda di includere il punto (.).

Se vuoi supportare tutti i tipi di file, seleziona la casella SupportsAnyFileType.

Per specificare i formati di dati supportati:

Apri il file manifesto.
Nella sezione Formati dati fai clic su Aggiungi nuovo.
Digita il nome del formato di dati che vuoi supportare, ad esempio "Testo".

Le API di condivisione supportano diversi formati standard, come testo, HTML e bitmap. Puoi anche specificare tipi di file e formati di dati personalizzati. In tal caso, non dimenticare che le app di origine devono supportare questi tipi e formati, altrimenti non potranno condividere i dati.

3. Gestione dell'attivazione della condivisione

Quando un utente seleziona la tua app, viene generato un evento activated dell'applicazione. L'app deve poter gestire questo evento per elaborare i dati che l'utente vuole condividere. Poiché un evento activated può essere generato per diversi motivi, la prima cosa da fare è verificare se il motivo per cui l'evento è stato generato è la condivisione dei dati.

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

I dati che l'utente vuole condividere sono contenuti in un oggetto ShareOperation. Puoi usare questo oggetto per verificare il formato dei dati che contiene. Ecco un esempio di un gestore eventi che gestisce contenuto condiviso in formato di testo normale:

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. Segnalazione dello stato delle condivisioni estese (per operazioni di lunga durata)

Nota

Il passaggio seguente è valido solo per le app di Windows Store. Puoi chiamare i metodi di segnalazione seguenti da Windows Phone 8.1, ma non verranno restituiti dati.

In alcuni casi l'app può impiegare qualche tempo a elaborare i dati che l'utente vuole condividere. Queste istanze di condivisione sono chiamate condivisioni estese. La condivisione di raccolte di file o immagini, ad esempio, è una condivisione estesa. Questi elementi sono più grandi di una semplice stringa di testo, pertanto l'elaborazione richiede più tempo.

Nota Se la tua app è in grado di ricevere solo elementi semplici, come testo o un collegamento ipertestuale, puoi ignorare questa sezione.

Come app di destinazione, la tua app non dovrebbe costringere l'utente a guardare l'interfaccia utente solo perché la tua app impiega più tempo per l'elaborazione dei dati. Dovresti invece usare l'oggetto ShareOperation per comunicare al sistema che la tua app sta ancora elaborando i dati. In questo modo l'utente potrà abbandonare l'interfaccia utente della tua app e riprendere la sua attività precedente. Nel frattempo, l'app continuerà a elaborare i dati in background.

shareOperation.reportStarted();

Dopo aver chiamato reportStarted, non aspettarti ulteriori interazioni dell'utente con l'app. Evita quindi di chiamare questo metodo finché l'app non è a un punto tale in cui può essere chiusa dall'utente.

Con una condivisione estesa, è possibile che l'utente chiuda l'app di origine prima che la tua app abbia recuperato tutti i dati dall'oggetto DataPackage. Per questo è importante segnalare al sistema quando l'app ha acquisito tutti i dati necessari. In questo modo il sistema può sospendere o terminare l'app di origine nel modo appropriato.

shareOperation.reportDataRetreived();

Se qualcosa non funziona, puoi anche chiamare reportError per inviare un messaggio di errore al sistema. L'utente vedrà il messaggio quando controllerà lo stato della condivisione. Non appena chiami reportError, l'app viene chiusa e la condivisione viene interrotta: se vorrà condividere lo stesso contenuto con la tua app, l'utente dovrà ripetere la procedura dall'inizio. A seconda dello scenario, puoi decidere che un determinato errore non è abbastanza grave da interrompere la condivisione. In tal caso puoi scegliere di non chiamare reportError e continuare invece la condivisione.

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

Quando usi questi metodi, normalmente li chiami nell'ordine descritto e non li chiami più di una volta. In alcuni casi, tuttavia, può accadere che un'app di destinazione chiami reportDataRetrieved prima di reportStarted. Ad esempio, l'app potrebbe recuperare i dati durante un'attività del gestore dell'attivazione, ma non chiamare reportStarted finché l'utente non fa clic sul pulsante Condividi.

Per osservare questo tipo di condivisione in azione, vedi il nostro esempio di app di destinazione per la condivisione di contenuto.

5. Segnalazione del completamento della condivisione

Infine, quando l'app completa l'elaborazione del contenuto condiviso, devi chiamare reportCompleted.

shareOperation.reportCompleted();

Dopo aver segnalato il completamento della condivisione, l'app si chiude.

6. Restituzione di un oggetto Quicklink in caso di condivisione riuscita

Nota

Gli oggetti QuickLink non sono supportati in Windows Phone 8.1. Durante un'operazione di condivisione le app di Windows Phone Store possono ricevere oggetti QuickLink, che tuttavia verranno automaticamente ignorati.

Quando un utente seleziona la tua app per ricevere contenuto condiviso, ti consigliamo vivamente di creare un oggetto QuickLink. Un oggetto QuickLink è una sorta di collegamento che semplifica agli utenti la condivisione di informazioni con l'app. Ad esempio, la tua app potrebbe creare un oggetto QuickLink che apre un nuovo messaggio di posta preconfigurato con l'indirizzo email di un amico.

Quando un utente seleziona la tua app per ricevere contenuto condiviso, ti consigliamo vivamente di creare un oggetto QuickLink. Un oggetto QuickLink è un collegamento che semplifica per gli utenti la condivisione di informazioni con l'app. Ad esempio, la tua app potrebbe creare un oggetto QuickLink che apre un nuovo messaggio di posta preconfigurato con l'indirizzo email di un amico.

Un oggetto QuickLink deve avere un titolo, un'icona e un ID. Il titolo (ad esempio "Email mamma") e l'icona compaiono quando l'utente tocca l'accesso alla condivisione. L'ID viene usato dall'app per identificare il QuickLink selezionato. Dopo aver creato un oggetto QuickLink, l'app restituisce il QuickLink al sistema chiamando il metodo reportCompleted dell'oggetto ShareOperation. Ecco un esempio:

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

Non dimenticare che la tua app è responsabile dell'archiviazione dell'ID dell'oggetto QuickLink e dei dati utente corrispondenti. Quando l'utente tocca il QuickLink, puoi recuperare il relativo ID tramite la proprietà ShareOperation.quickLinkId. Quando una condivisione con un QuickLink dà esito positivo, dovresti restituire lo stesso QuickLink quando chiami reportCompleted.

Riepilogo e passaggi successivi

A questo punto dovresti esserti fatto un'idea di come ricevere contenuto condiviso e di come creare un oggetto QuickLink che semplifichi agli utenti la condivisione di contenuto con la tua app.

Per ulteriori informazioni o per ottenere altri esempi specifici su come aggiungere la condivisione all'app, ti può essere utile vedere:

Nota Il debug di un'app di destinazione di condivisione è un processo diverso rispetto al debug di altri tipi di app. Per altre informazioni, vedi Linee guida per il debug delle app di destinazione.

Argomenti correlati

Scelta dei formati di dati per la condivisione

Linee guida ed elenco di controllo per la condivisione di contenuto

Guida introduttiva: Condivisione di contenuto