Come condividere file (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 ]

Gli utenti hanno spesso l'esigenza di condividere i file con altre persone o app. Grazie alla funzionalità di condivisione, la tua app può supportare con facilità attività che vanno dall'invio di un file a un collega tramite e-mail alla condivisione di un'insieme di foto delle vacanze.

Quando supporti la condivisione dei file, devi considerare quando saranno pronti i file nella tua app. In genere i file saranno probabilmente pronti per l'uso e in tal caso i passaggi contenuti in questo argomento sono quelli da seguire. Se invece la tua app deve eseguire altre operazioni prima che i file siano pronti, ad esempio se deve convertire i file da un formato in un altro, leggi l'argomento Come supportare le operazioni pull. Tale argomento spiega come usare una funzione di delegato in modo che le app di destinazione possano effettuare il pull del contenuto condiviso dalla tua app, senza che sia la tua app a dover effettuare il push.

Cosa sapere

Tecnologie

Windows.ApplicationModel.DataTransfer

Prerequisiti

Occorre avere già familiarità con Visual Studio e i modelli associati.
Occorre avere già familiarità con JavaScript.
Occorre saper recuperare i file e altri dati, usando FileOpenPicker ad esempio. Per saperne di più, vedi Accesso ai file mediante le selezioni file.

Istruzioni

Passaggio 1: Creare una funzione gestore pulsanti per consentire all'utente di scegliere un file immagine

Il codice seguente per il gestore pulsanti permette all'utente di selezionare un file immagine. Questo file viene usato nei passaggi successivi di questa esercitazione.

Nota

Il codice seguente usa pickSingleFileAsync. In Windows Phone 8.1, è invece necessario usare pickSingleFileAndContinue.

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

Passaggio 2: Impostare l'app come origine di condivisione

L'oggetto DataTransferManager è il punto di partenza principale per qualsiasi operazione di condivisione. Aggiungi un gestore per l'evento DataRequested da attivare 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.

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

I passaggi rimanenti riguardano l'implementazione della funzione shareStorageItemsHandler.

Passaggio 3: Recuperare un oggetto DataRequest

Quando si verifica un evento datarequested, l'app riceve un oggetto DataRequest. Questo oggetto contiene un DataPackage che puoi usare per fornire il contenuto che l'utente vuole condividere.

var request = e.request;

Passaggio 4: Impostare le proprietà di titolo e descrizione

request.data.properties.title = "Share StorageItems Example";
request.data.properties.description = "Demonstrates how to share files.";

Passaggio 5: Aggiungere i file all'oggetto DataPackage

Per aggiungere i file all'oggetto DataPackage devi usare il metodo setStorageItems.

request.data.setStorageItems([imageFile]);

Osservazioni

Per impostazione predefinita, setStorageItems offre "cloni" di storageItems di sola lettura da condividere con le app di destinazione. Dopo aver chiamato setStorageItems, le eventuali nuove proprietà impostate sui singoli elementi di archiviazione non verranno riflesse negli elementi clonati. Per questo motivo devi assicurarti che i file siano assolutamente pronti per la condivisione prima di aggiungerli all'oggetto DataPackage.

Inoltre, se desideri che un'app di destinazione disponga di funzionalità di lettura/scrittura su storageItems, usa la versione overload del metodo setStorageItems, che consente di specificare le proprietà read-only o read/write. Ad esempio, un'app di origine che chiede all'app di destinazione di eseguire un'operazione di eliminazione dopo la copia, deve specificare la proprietà di lettura/scrittura per consentire all'app di destinazione di eliminare i file di origine dopo averli copiati.

Se la tua app deve usare un'operazione asincrona per preparare l'immagine o l'anteprima, dovrai usare il modello di differimento. Per saperne di più, vedi Come effettuare chiamate asincrone nel gestore dell'evento DataRequested.

Se la tua app impiega molto tempo (più di 200 millisecondi) per approntare l'immagine, devi usare una funzione di delegato per condividerla. La procedura è descritta nell'argomento Come supportare le operazioni pull. Se decidi di usare una funzione di delegato, devi impostare la proprietà FileTypes in DataPackage prima di aggiungere i file.

Esempio completo

Ecco un esempio di una funzione che imposta alcuni file che un utente può condividere. Per un esempio più completo, guarda il nostro esempio della Code Gallery.

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

function shareStorageItemsHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share StorageItems Example";
    request.data.properties.description = "Demonstrates how to share files.";
    request.data.setStorageItems([imageFile]);
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app is newly launched; register it as a share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", shareStorageItemsHandler);
            // Setup the button handler to pick image file
            document.getElementById("chooseImageButton").addEventListener("click", pickImageFile, false);
        } else {
            // TODO: This app was reactivated from suspension.
            // Restore the app state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};