Come ricevere 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 ]

La condivisione di file richiede una maggiore preparazione rispetto a tipi di dati più semplici, ad esempio testo. Quando condividi file, devi considerare il tempo necessario per elaborarli.

Se ritieni che l'app abbia bisogno di tempo per elaborare i file che un utente vuole condividere, assicurati di chiamare reportStarted prima di iniziare a elaborarli. Con questo metodo il sistema manterrà attiva l'app fino al termine dell'elaborazione. Al termine dell'elaborazione, chiama reportCompleted per completare l'operazione di condivisione. Per altre informazioni, vedi la sezione "Segnalazione dello stato delle condivisioni estese" in Guida introduttiva: Ricezione di contenuto condiviso.

Cosa sapere

Tecnologie

Windows.ApplicationModel.DataTransfer

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 destinazione:

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 i tipi di file suportati dall'app.

Puoi specificare i tipi di file supportati dalla tua app indicando le relative estensioni nel manifesto dell'app:

Apri il file manifesto.
Nella sezione Formati dati fai clic su Aggiungi nuovo.
Digita l'estensione del nome file, ad esempio ".txt" (senza le virgolette).
Ripeti il passaggio precedente per ogni altro tipo di file.

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

<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <SupportedFileTypes>
        <FileType>.txt</FileType>
    </ShareTarget>
  </Extension>
</Extensions>

Nota Non è necessario specificare gli elementi StorageItems nella sezione relativa ai formati dei dati. Il relativo supporto viene desunto dalla sezione SupportedFileTypes del manifesto. Se l'app supporta tutti i tipi di file, puoi specificarli nel manifesto selezionando Supporta tutti i tipi di file.

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 DataPackageView contiene StorageItems

L'oggetto ShareOperation contiene un oggetto DataPackageView. Questo oggetto è 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 contiene StorageItems.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
    // Data being shared contains one or more StorageItem. Code to process the StorageItems 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 i file

Per recuperare i file, chiama il metodo DataPackageView.GetStorageItemsAsync.

shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
    var fileList = "";
    for (var i = 0; i < storageItems.size; i++) {
        fileList += storageItems.getAt(i).name;
        if (i < storageItems.size - 1) {
            fileList += ", ";
        }
    }
    // In this example, we only display the file names. 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").innerText = "Files: " + fileList;
});

Nota

L'elaborazione dei file può richiedere tempo. È importante non forzare l'utente ad attendere fino a quando l'app ha completato il caricamento e l'elaborazione dei dati. In Windows 8.1 puoi chiamare il metodo reportStarted per fare sapere al sistema che la tua app ha iniziato a elaborare il contenuto condiviso. Il sistema mantiene attiva l'app finché non chiami reportCompleted, anche se l'utente chiude la tua app per tornare all'app di origine. Per altre informazioni, vedi la sezione relativa alla segnalazione dello stato delle condivisioni estese, in Guida introduttiva: Ricezione di contenuto condiviso.

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.

Esempio completo

var shareOperation = null;

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
        shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
            var fileList = "";
            for (var i = 0; i < storageItems.size; i++) {
                fileList += storageItems.getAt(i).name;
                if (i < storageItems.size - 1) {
                    fileList += ", ";
                }
            }
            // In this example, we only display the file names. 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").innerText = "Files: " + fileList;
        });
    }
}

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