Inicio rápido: acceso a archivos mediante selectores de archivos (HTML)

Artículo
12/12/2015

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

Se puede acceder a archivos y carpetas mediante el selector de archivos, que permite a los usuarios seleccionar archivos y carpetas. Puedes usar la clase fileOpenPicker para acceder a archivos y la clase folderPicker para acceder a las carpetas.

Requisitos previos

Conocer la programación asincrónica para aplicaciones de Windows en tiempo de ejecución con JavaScript

Puedes aprender cómo escribir aplicaciones asincrónicas en el inicio rápido sobre el uso de promesas en JavaScript.

Interfaz de usuario del selector de archivos

Los selectores de archivos incluyen áreas en la parte superior e inferior de la pantalla que muestran información para guiar al usuario y ofrecen una experiencia coherente cuando los usuarios acceden a los archivos o los guardan.

La información que se muestra incluye:

La ubicación actual, que se encuentra en la parte superior izquierda
Una cesta de elementos que eligió el usuario, que se encuentra junto al botón
Una lista desplegable de ubicaciones que el usuario puede examinar, que se puede seleccionar desde el símbolo circunflejo invertido en la parte superior izquierda

Por ejemplo, esta captura de pantalla muestra un selector de archivos al que se llamó para permitir al usuario elegir algunos archivos. En la captura de pantalla, el usuario seleccionó dos archivos. Captura de pantalla de un selector de archivos con dos archivos seleccionados para abrirlos.

El usuario puede ver la lista desplegable de ubicaciones disponibles, como la lista mostrada en la captura de pantalla de la derecha, si selecciona el símbolo circunflejo invertido de la parte superior izquierda del selector de archivos. Entre ellas se incluyen ubicaciones del sistema de archivos, como la carpeta Música o Descargas. También incluyen otras aplicaciones, si estas otras aplicaciones (como Microsoft OneDrive) participan en los contratos del selector de archivos, lo cual se puede ver al final de la lista en la captura de pantalla.

Captura de pantalla recortada del selector de archivos que muestra la lista desplegable de ubicaciones en la parte superior izquierda.

Completa el código para seleccionar un archivo

La muestra de selector de archivos ilustra cómo usar fileOpenPicker para que el usuario pueda seleccionar un solo archivo.

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

Para obtener el código completo para seleccionar varios archivos, consulta la muestra de selector de archivos.

Tutorial para seleccionar un archivo

Llamar al selector de archivos requiere dos tareas básicas: crear y personalizar un objeto de selector de archivos y mostrar el selector de archivos para que el usuario pueda seleccionar uno o varios elementos.

Crear y personalizar un selector para abrir archivos

Usa fileOpenPicker si el usuario está seleccionando uno o más archivos. Esta clase se puede personalizar. Para ello, configura las propiedades en el objeto que vayas a crear.

La muestra de selector de archivos ilustra cómo crear y personalizar un objeto 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"]);
```
Debes establecer las propiedades en el objeto del selector de archivos que sean importantes para los usuarios y la aplicación. Para obtener directrices que te ayudarán a decidir cómo personalizar el selector de archivos, consulta Directrices y lista de comprobación para selectores de archivos. Continúa leyendo para ver por qué establecemos ciertas propiedades para personalizar los selectores de archivos en la muestra de selector de archivos.

Explicación de las personalizaciones de fileOpenPicker de la muestra de selector de archivos

La muestra de selector de archivos crea una representación visual enriquecida en una práctica ubicación que el usuario puede seleccionar estableciendo tres propiedades fileOpenPicker: viewMode, suggestedStartLocation y fileTypeFilter.
- Al establecer openPicker.viewMode en el valor de enum PickerViewMode thumbnail se crea una representación visual enriquecida con miniaturas de imágenes para representar archivos en el selector de archivos.
```
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
  Debes considerar la posibilidad de establecer viewMode en PickerViewMode.thumbnail si estás usando el selector de archivos para mostrar archivos visuales como imágenes o vídeos. De lo contrario, usa PickerViewMode.list.
  
  En algunos casos, es posible que el usuario desee seleccionar una imagen, un vídeo o cualquier otro tipo de archivo. Por ejemplo, es posible que el usuario seleccione un archivo para adjuntarlo a un correo electrónico o enviarlo a través de mensajería instantánea. En este caso, debes admitir ambos modos de vista; para ello, agrega dos controles de interfaz de usuario a la aplicación. Un control debe llamar al selector de archivos usando el modo de vista thumbnail para que el usuario pueda seleccionar imágenes y vídeos. El otro control debe llamar al selector de archivos usando el modo de vista list para que el usuario pueda seleccionar otros tipos de archivos. Por ejemplo, una aplicación de correo tendría dos botones: Adjuntar imagen o vídeo y Adjuntar documento.
- Establecer openPicker.suggestedStartLocation en Imágenes mediante PickerLocationId.picturesLibrary permite al usuario iniciar en una ubicación donde probablemente pueda encontrar imágenes.
```
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
```
  Debes establecer suggestedStartLocation en la ubicación del sistema de archivos que sea apropiada para el tipo de archivo que se está seleccionando. Si el usuario está seleccionando música, imágenes o vídeos, establece la ubicación del inicio en Música, Imágenes o Vídeos, respectivamente. Para todos los demás tipos de archivos, establece la ubicación de inicio en Documentos. Se trata simplemente de una ubicación de inicio. Los usuarios pueden desplazarse a otras ubicaciones mientras estén usando el selector de archivos.
  
  Por otra parte, no siempre se usa suggestedStartLocation como ubicación de inicio para el selector de archivos. Para ofrecer al usuario sensación de coherencia, el selector de archivos recuerda la última ubicación que el usuario visualizó y, por lo general, se inicia en esa ubicación.
- Utilizar openPicker.fileTypeFilter.replaceAll para especificar los tipos de archivos que el usuario puede ver en el selector de archivos te permite mantener al usuario concentrado en la selección de archivos que sean relevantes y utilizables.
```
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
  Debes considerar la posibilidad de especificar los tipos de archivos que se muestran en el selector de archivos para que los archivos que se muestren sean relevantes. Por ejemplo, si tu aplicación es un reproductor de vídeo, puedes usar la propiedad fileTypeFilter para asegurarte de que los archivos que se muestran en el selector de archivos tengan el formato de vídeo que admite tu reproductor, según la extensión del nombre del archivo de vídeo.
  
  Si deseas agregar tipos de archivo al fileTypeFilter en lugar de reemplazar entradas, puedes usar el método append en lugar de replaceAll.
Mostrar fileOpenPicker

Ahora puedes mostrar el selector de archivos para que el usuario pueda seleccionar un solo archivo o varios:
- Mostrar para que el usuario pueda seleccionar un solo archivo
  
  Después de crear y personalizar el selector de archivos, llama a para permitir al usuario seleccionar un archivo fileOpenPicker.pickSingleFileAsync. Cuando el usuario elige un archivo, fileOpenPicker.pickSingleFileAsync devuelve un objeto storageFile que representa el archivo seleccionado.
  
  La muestra de selector de archivos ilustra cómo presentar el selector de archivos para que el usuario pueda elegir un archivo y cómo capturar el archivo seleccionado para procesarlo.
```
// 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");
    }
});
```
  Cuando se completa la llamada openPicker.pickSingleFileAsync, el archivo seleccionado, que se representa con un objeto storageFile, se pasa a un literal de función para procesarlo como el parámetro file. Si la operación se canceló sin nada seleccionado, este parámetro será null.
- Mostrar para que el usuario pueda seleccionar varios archivos
  
  Después de crear y personalizar un selector de archivos, permite al usuario elegir varios archivos al llamar a fileOpenPicker.pickMultipleFilesAsync.
  
  Cuando el usuario elige varios archivos, fileOpenPicker.pickMultipleFilesAsync devuelve una lista de objetos storageFile que representan los archivos seleccionados.
  
  La muestra de selector de archivos ilustra cómo presentar el selector de archivos para que el usuario pueda elegir varios archivos y cómo capturar la lista de archivos seleccionados para procesarlos.
```
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");
    }
});
```
  Cuando se completa la llamada openPicker.pickMultipleFilesAsync, la lista de objetos seleccionados se pasa a un literal de función para procesarla como parámetro files. Los archivos seleccionados en la lista se representan mediante objetos storageFile. Si la operación se canceló sin nada seleccionado, este parámetro tendrá un tamaño mayor que 0.

Completa el código para seleccionar una carpeta

La muestra de selector de archivos ilustra cómo usar folderPicker para que el usuario pueda seleccionar una sola carpeta.

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

Tutorial para seleccionar una carpeta

Crear y personalizar un foldPicker

Usa folderPicker si el usuario está seleccionando una carpeta. Esta clase se puede personalizar. Para ello, configura las propiedades en el objeto que vayas a crear.

La muestra de selector de archivos ilustra cómo crear y personalizar un objeto 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"]);
```
Debes establecer las propiedades en el objeto del selector de archivos que sean importantes para los usuarios y la aplicación. Para obtener directrices que te ayudarán a decidir cómo personalizar el selector de archivos, consulta Directrices y lista de comprobación para selectores de archivos. Continúa leyendo para ver por qué establecemos ciertas propiedades para personalizar los selectores de archivos en la muestra de selector de archivos.

Explicación de las personalizaciones de folderPicker de la muestra de selector de archivos

La muestra de selector de archivos personaliza el selector de archivos para que seleccione carpetas mediante tres propiedades folderPicker: viewMode, suggestedStartLocation y fileTypeFilter.
- Usar el PickerViewMode.list predeterminado para folderPicker.viewMode nos permite crear una visualización tipo lista en el selector de archivos. Esta lista sirve para seleccionar archivos que no son muy visuales, como los documentos.
  
  Debes considerar la posibilidad de establecer viewMode en PickerViewMode.thumbnail si estás usando el selector de archivos para mostrar archivos visuales como imágenes o vídeos. De lo contrario, usa PickerViewMode.list.
  
  Si estás mostrando archivos visuales como imágenes o vídeos, debes establecer folderPicker.viewMode en thumbnail de esta manera:
```
folderPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
- Establecer folderPicker.suggestedStartLocation en el escritorio del usuario mediante PickerLocationId.desktop permite al usuario comenzar en una ubicación familiar y muy utilizada.
```
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
```
  Debes establecer suggestedStartLocation en la ubicación del sistema de archivos que sea apropiada para el tipo de carpeta que el usuario desea seleccionar. Por ejemplo, si el usuario está seleccionando un carpeta que contiene archivos de música, debes iniciarlos en Música. Esta es simplemente una ubicación de inicio, los usuarios pueden desplazarse a otras ubicaciones mientras estén usando el selector de archivos.
  
  Por otra parte, no siempre se usa suggestedStartLocation como ubicación de inicio para el selector de archivos. Para ofrecer al usuario sensación de coherencia, el selector de archivos recuerda la última ubicación que el usuario visualizó y, por lo general, se inicia en esa ubicación.
- Utilizar folderPicker.fileTypeFilter.replaceAll para especificar los tipos de archivos que el usuario puede ver en el selector de archivos nos permite mantener al usuario concentrado en la selección de una carpeta relevante.
```
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  Los usuarios solo pueden seleccionar carpetas a través de un folderPicker, no podrán seleccionar archivos individuales. Sin embargo, mostrar archivos importantes en el folderPicker ayuda a los usuarios a determinar qué carpeta desean seleccionar. Por ejemplo, al utilizar folderPicker para seleccionar una ubicación desde la cual importar imágenes, mostrar archivos de imágenes ayuda al usuario a identificar qué elementos se importarán cuando se seleccione la ubicación.
Mostrar folderPicker para que el usuario pueda seleccionar una sola carpeta

Después de crear y personalizar un folderPicker, permite al usuario elegir una carpeta llamando a folderPicker.pickSingleFolderAsync. Cuando el usuario elige una carpeta, folderPicker.pickSingleFolderAsync devuelve un storageFolder que representa la carpeta seleccionada. Debes capturar y procesar esta carpeta con done para que las excepciones se propaguen correctamente.

La muestra de selector de archivos ilustra cómo presentar el selector de archivos para que el usuario pueda elegir una carpeta y cómo capturar la carpeta seleccionada para procesarla.
```
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");
    }
});
```
Cuando se completa la llamada folderPicker.pickSingleFolderAsync , la carpeta seleccionada se pasa a un literal de función para procesarla como el parámetro folder. La carpeta seleccionada se representa mediante un objeto storageFolder. Si la operación se canceló sin nada seleccionado, este parámetro será null.

Resumen y siguientes pasos

Si usas código similar al que se muestra aquí, la aplicación mostrará un selector de archivos que permite a los usuarios seleccionar uno o más archivos o carpetas que se pueden abrir con tu aplicación.

Sugerencia Cuando la aplicación accede a un archivo o a una carpeta a través del selector de archivos, agrega ese elemento a futureAccessList o mostRecentlyUsedList de la aplicación para realizar el seguimiento del elemento. Obtendrás más información sobre cómo usar estas listas en el tema sobre cómo hacer un seguimiento de los archivos y carpetas usados recientemente.

Para obtener más información acerca de cómo leer archivos y escribir en ellos, consulta Inicio rápido: lectura y escritura de archivos y la Muestra de acceso de archivos. Para aprender a trabajar con archivos de imágenes, consulta Cómo seleccionar y mostrar una imagen, Cómo decodificar una imagen y la Muestra del uso de un blob para guardar y cargar contenido.

Si quieres saber más sobre las llamadas al selector de archivos para guardar archivos, consulta Cómo guardar archivos mediante selectores de archivos.

Si quieres que tu aplicación proporcione archivos, una ubicación para guardar o actualizaciones de archivos a otras aplicaciones, consulta Inicio rápido: integrar con contratos del selector de archivos.