Guida introduttiva: Accesso a file con selezione 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 ]

Accedere a file e cartelle tramite selezione file consentendo agli utenti di selezionare file e cartelle. Puoi usare la classe fileOpenPicker per accedere ai file e la classe folderPicker per accedere alle cartelle.

Prerequisiti

Conoscere le tecniche di programmazione asincrona per le app di Windows Runtime scritte in JavaScript

Per informazioni su come scrivere app asincrone, vedi Guida introduttiva: Uso delle promesse in JavaScript.

Interfaccia utente di selezione file

Le selezioni file presentano aree nelle parti superiore e inferiore dello schermo in cui vengono visualizzate informazioni per orientare gli utenti e offrire loro un'esperienza coerente per l'accesso ai file o il loro salvataggio.

Le informazioni visualizzate includono quanto segue:

Il percorso corrente in alto a sinistra
Una serie di elementi che l'utente può scegliere lungo la parte inferiore
Un elenco a discesa di percorsi che l'utente può esplorare e selezionabili dal cursore a discesa in alto a sinistra

Ad esempio, questa schermata mostra una selezione file che è stata chiamata per consentire all'utente di scegliere alcuni file. Nello screenshot l'utente ha selezionato due file. Acquisizione schermo della selezione file, con due file selezionati per l'apertura.

L'utente può visualizzare l'elenco a discesa dei percorsi disponibili, come illustrato a destra nella cattura di schermata, selezionando il cursore a discesa in alto a sinistra nella selezione file. Sono inclusi i percorsi del file system, come la cartella Musica o la cartella Download. Sono incluse anche le altre app (ad esempio, Microsoft OneDrive), se aderiscono ai contratti di selezione file, visualizzati in fondo all'elenco nella cattura di schermata.

Cattura di schermata ritagliata di una selezione file in cui viene mostrato l'elenco a discesa dei percorsi in alto a sinistra.

Codice completo per selezionare un file

L'esempio di selezione file dimostra come usare fileOpenPicker per consentire all'utente di selezionare un solo file.

// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);

// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

Per conoscere il codice completo per selezionare più file, vedi l'esempio di selezione file.

Esercitazione per selezionare un file

Per chiamare la selezione file sono necessarie due attività basilari: creare e personalizzare un oggetto selezione file e visualizzare la selezione file in modo tale che l'utente possa selezionare uno o più elementi.

Creare e personalizzare una selezione per apertura file

Usa fileOpenPicker se l'utente deve selezionare uno o più file. Puoi personalizzare questa classe impostando le proprietà sull'oggetto che crei.

L'esempio di selezione file illustra come creare e personalizzare un oggetto fileOpenPicker.
```
// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
Devi impostare le proprietà dell'oggetto selezione file rilevanti per i tuoi utenti e per la tua app. Per indicazioni su come personalizzare la selezione file, vedi Linee guida ed elenco di controllo per la selezione file. Per conoscere i motivi per cui impostiamo le proprietà per personalizzare le selezioni file nell'esempio di selezione file, continua a leggere.

Dettagli sulle personalizzazioni della selezione per apertura file

L'esempio di selezione file crea una visualizzazione ricca di immagini in una posizione comoda, dalla quale l'utente può effettuare la propria selezione impostando tre proprietà di fileOpenPicker: viewMode, suggestedStartLocation e fileTypeFilter.
- Impostando openPicker.viewMode sul valore di enumerazione thumbnail PickerViewMode, creeremo una visualizzazione ricca grazie all'uso di anteprime delle immagini per rappresentare i file nella selezione file.
```
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
  È consigliabile impostare viewMode su PickerViewMode.thumbnail se usi la selezione file per visualizzare file grafici, come immagini o video. In caso contrario, usa PickerViewMode.list.
  
  In alcuni casi l'utente potrebbe voler selezionare un'immagine o un video o qualsiasi altro tipo di file. Ad esempio, l'utente potrebbe selezionare un file da allegare a un messaggio email o da inviare tramite IM. In tal caso, dovresti supportare entrambe le modalità di visualizzazione aggiungendo nella tua app due controlli dell'interfaccia utente. Un controllo dovrebbe chiamare la selezione utente usando la modalità di visualizzazione thumbnail, in modo da consentire all'utente di selezionare immagini e video. L'altro controllo dovrebbe chiamare la selezione utente usando la modalità di visualizzazione list, in modo da consentire all'utente di selezionare altri tipi di file. Ad esempio, un'app di posta potrebbe avere due pulsanti: Allega immagine o video e Allega documento.
- Impostando openPicker.suggestedStartLocation su Immagini mediante PickerLocationId.picturesLibrary, l'utente può iniziare da un percorso in cui è probabile che siano contenute immagini.
```
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
```
  Devi impostare suggestedStartLocation sul percorso del file system più idoneo per il tipo di file che verrà selezionato. Se l'utente deve selezionare musica, immagini o video, imposta il percorso iniziale rispettivamente su Musica, Immagini o Video. Per tutti gli altri tipi di file, imposta il percorso iniziale su Documenti. Si tratta semplicemente di un percorso iniziale: gli utenti possono spostarsi in altri percorsi usando la selezione file.
  
  Inoltre non sempre il percorso iniziale per la selezione file che viene usato è suggestedStartLocation Per dare coerenza all'esperienza utente, la selezione file ricorda l'ultimo percorso visualizzato dall'utente e in genere lo ripropone per primo.
- L'uso di openPicker.fileTypeFilter.replaceAll per specificare i tipi di file che l'utente può visualizzare nella selezione file può aiutare a mantenere concentrato l'utente sulla scelta di file effettivamente pertinenti e utili.
```
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
  È consigliabile specificare i tipi di file da visualizzare nella selezione file in modo da circoscrivere la visualizzazione ai soli file pertinenti. Se ad esempio la tua app è un lettore video, puoi usare la proprietà fileTypeFilter per assicurarti che i file visualizzati nella selezione file siano nei formati video supportati dal lettore, sulla base dell'estensione del nome file del video.
  
  Se vuoi aggiungere tipi di file a fileTypeFilter invece di sostituire le voci, puoi usare il metodo append invece del metodo replaceAll.
Visualizzare la selezione per apertura file

Puoi visualizzare la selezione file in modo da consentire all'utente di selezionare un solo file o più file:
- Visualizzazione per la selezione di un solo file
  
  Dopo avere creato e personalizzato la selezione file, consenti all'utente di selezionare un solo file chiamando fileOpenPicker.pickSingleFileAsync Quando l'utente seleziona un file, fileOpenPicker.pickSingleFileAsync restituisce un oggetto storageFile che rappresenta il file selezionato.
  
  L'esempio di selezione file illustra come visualizzare l'utilità di selezione file per consentire all'utente di selezionare un unico file e come acquisire il file selezionato per l'elaborazione.
```
// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  Al termine della chiamata a openPicker.pickSingleFileAsync, il file selezionato (rappresentato da un oggetto storageFile) viene passato a un valore letterale di funzione per l'elaborazione come parametro file. Se l'operazione è stata annullata e non è stata effettuata nessuna selezione, questo parametro sarà null.
- Visualizzazione per la selezione di più file
  
  Dopo aver creato e personalizzato una selezione file, consenti all'utente di selezionare più file chiamando fileOpenPicker.pickMultipleFilesAsync.
  
  Quando l'utente seleziona più file, fileOpenPicker.pickMultipleFilesAsync restituisce un elenco di oggetti storageFile che rappresentano i file selezionati.
  
  L'esempio di selezione file illustra come visualizzare la selezione file per consentire all'utente di selezionare più file e come acquisire l'elenco dei file selezionati per l'elaborazione.
```
openPicker.pickMultipleFilesAsync().then(function (files) {
    if (files.size > 0) {
        // Application now has read/write access to the picked file(s)
        var outputString = "Picked files:\n";
        for (var i = 0; i < files.size; i++) {
            outputString = outputString + files[i].name + "\n";
        }
        WinJS.log && WinJS.log(outputString, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
  Al termine della chiamata a openPicker.pickMultipleFilesAsync, l'elenco di file selezionati viene passato a un valore letterale di funzione per l'elaborazione come parametro files. I file selezionati nell'elenco sono rappresentati da oggetti storageFile. Se l'operazione è stata annullata e non è stata effettuata nessuna selezione, questo parametro avrà dimensioni maggiori di 0.

Codice completo per selezionare una cartella

L'esempio di selezione file dimostra come usare folderPicker per consentire all'utente di selezionare una cartella singola.

// Verify that we are currently not snapped, or that we can unsnap to open the picker
var currentState = Windows.UI.ViewManagement.ApplicationView.value;
if (currentState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
    !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
    // Fail silently if we can't unsnap
    return;
}

// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);

folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

Esercitazione per selezionare una cartella

Creare e personalizzare una selezione cartelle

Usa folderPicker se l'utente deve selezionare una cartella. Puoi personalizzare questa classe impostando le proprietà sull'oggetto che crei.

L'esempio di selezione file illustra come creare e personalizzare un oggetto folderPicker.
```
// Create the picker object and set options
var folderPicker = new Windows.Storage.Pickers.FolderPicker;
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
Devi impostare le proprietà dell'oggetto selezione file rilevanti per i tuoi utenti e per la tua app. Per indicazioni su come personalizzare la selezione file, vedi Linee guida ed elenco di controllo per la selezione file. Per conoscere i motivi per cui impostiamo le proprietà per personalizzare le selezioni file nell'esempio di selezione file, continua a leggere.

Dettagli sulle personalizzazioni della selezione cartelle

L'esempio di selezione file personalizza la selezione file in modo da selezionare cartelle tramite l'uso di tre proprietà di folderPicker: viewMode, suggestedStartLocation e fileTypeFilter.
- Usando il metodo predefinito PickerViewMode.list per folderPicker.viewMode, possiamo creare una visualizzazione tipo elenco nella selezione file. L'elenco è pratico per selezionare i file che non hanno una resa prevalentemente grafica, ad esempio i documenti.
  
  È consigliabile impostare viewMode su PickerViewMode.thumbnail se usi la selezione file per visualizzare file grafici, come immagini o video. In caso contrario, usa PickerViewMode.list.
  
  Se devi visualizzare file grafici come immagini o video, devi impostare folderPicker.viewMode su thumbnail, in questo modo:
```
folderPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
- Impostando folderPicker.suggestedStartLocation sul desktop dell'utente tramite PickerLocationId.desktop, consentiamo all'utente di iniziare da un percorso familiare e molto usato.
```
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
```
  Devi impostare suggestedStartLocation sul percorso del file system più idoneo per il tipo di file o cartella che l'utente vorrà selezionare. Se ad esempio l'utente deve selezionare una cartella che contenga file musicali, il percorso iniziale più idoneo è la cartella Musica. Si tratta semplicemente di un percorso iniziale, dopodiché gli utenti possono spostarsi in altri percorsi usando la selezione file.
  
  Inoltre non sempre il percorso iniziale per la selezione file che viene usato è suggestedStartLocation Per dare coerenza all'esperienza utente, la selezione file ricorda l'ultimo percorso visualizzato dall'utente e in genere lo ripropone per primo.
- L'uso di folderPicker.fileTypeFilter.replaceAll per specificare i tipi di file che l'utente può visualizzare nella selezione file può aiutare a mantenere concentrato l'utente sulla scelta di una cartella effettivamente pertinente e utile.
```
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  Con folderPicker, gli utenti possono solo selezionare cartelle e non possono selezionare singoli file. Tuttavia visualizzando i file pertinenti in folderPicker, è possibile aiutare gli utenti a scegliere la cartella pertinente. Ad esempio, quando usi folderPicker per selezionare un percorso da cui importare immagini, visualizzando i file immagine potrai aiutare l'utente a identificare quali elementi verranno importati selezionando tale percorso.
Visualizzazione della selezione cartelle per la selezione di una sola cartella

Dopo avere creato e personalizzato un folderPicker, puoi consentire all'utente di selezionare una cartella singola chiamando folderPicker.pickSingleFolderAsync. Quando l'utente seleziona una cartella, folderPicker.pickSingleFolderAsync restituisce un oggetto storageFolder che rappresenta la cartella selezionata. Devi acquisire ed elaborare questa cartella usando done, in modo che le eccezioni si propaghino correttamente.

L'esempio di selezione file dimostra come visualizzare la selezione file per consentire all'utente di selezionare una cartella e come acquisire la cartella selezionata per l'elaborazione.
```
folderPicker.pickSingleFolderAsync().then(function (folder) {
    if (folder) {
        // Application now has read/write access to all contents in the picked folder (including sub-folder contents)
        // Cache folder so the contents can be accessed at a later time
        Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.addOrReplace("PickedFolderToken", folder);
        WinJS.log && WinJS.log("Picked folder: " + folder.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
```
Al completamento della chiamata a folderPicker.pickSingleFolderAsync, la cartella selezionata viene passata a un valore letterale di funzione per l'elaborazione come parametro folder. La cartella selezionata è rappresentata da un oggetto storageFolder. Se l'operazione è stata annullata e non è stata effettuata nessuna selezione, questo parametro sarà null.

Riepilogo e passaggi successivi

Se usi codice simile a quello visualizzato qui, la tua app visualizzerà una selezione file che consente agli utenti di selezionare uno o più file o cartelle che la tua app potrà poi aprire.

Suggerimento Ogni volta che la tua app accede a un file o a una cartella tramite la selezione file, aggiungi tale elemento agli elenchi futureAccessList o mostRecentlyUsedList dell'app per tenerne traccia. Per ulteriori informazioni sull'uso di questi elenchi, vedi Come tenere traccia di cartelle e file usati di recente.

Per informazioni sulla lettura e la scrittura di file, vedi Guida introduttiva: Lettura e scrittura di un file, oltre all'esempio di accesso ai file. Per altre informazioni sull'uso dei file immagine, vedi Come selezionare e visualizzare un'immagine, Come decodificare un'immagine e l'argomento relativo all'uso di un blob per salvare e caricare un esempio di contenuto.

Per informazioni su come chiamare la selezione file per salvare i file, vedi Come salvare file tramite selezioni file.

Se vuoi che la tua app fornisca file, un percorso di salvataggio o aggiornamenti dei file ad altre app, vedi Guida introduttiva: Integrazione con i contratti di selezione file.