Краткое руководство. Доступ к файлам с помощью средств выбора файлов (HTML)

Статья
12/12/2015

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]

В этой статье описывается, как получить доступ к файлам и папкам с помощью средства выбора файлов, позволяя пользователям выбирать файлы и папки. Можно использовать класс fileOpenPicker для получения доступа к файлам и folderPicker для получения доступа к папкам.

Необходимые условия

Понятие об асинхронном программировании для приложений среды выполнения Windows на JavaScript

Сведения о записи асинхронных приложений см. в статье Краткое руководство: использование объектов Promise в JavaScript.

пользовательский интерфейс средства выбора файлов

Средства выбора файлов в верхней и нижней частях экрана имеют области, в которых отображаются сведения, позволяющие сориентировать пользователя и обеспечить ему привычное взаимодействие с системой при доступе к файлам и их сохранении.

Отображаемые сведения включают:

текущее расположение в левом верхнем углу;
корзину элементов, выбранных пользователем, в нижней части;
раскрывающийся список расположений, которые пользователь может просмотреть (чтобы раскрыть список, щелкните знак перевернутой крышки в левом верхнем углу).

Например, на этом снимке экрана показано средство выбора файлов, которое было вызвано для того, чтобы пользователь смог выбрать несколько файлов. На этом снимке экрана пользователь выбрал два файла. Снимок экрана средства выбора файлов, в котором выбрано два файла.

Щелкнув знак перевернутой крышки в левом верхнем углу средства выбора файлов, пользователь может просмотреть раскрывающийся список доступных расположений, аналогичный списку на снимке экрана справа. Они включают расположения в файловой системе, например папку "Музыка" или "Загрузки". Также включаются и другие приложения, если они (например, Microsoft OneDrive) участвуют в контракте выбора файлов, который можно видеть в нижней части списка на снимке экрана.

Обрезанный снимок экрана для средства выбора файлов, на котором в левом верхнем углу виден раскрывающийся список расположений.

Полный код для выбора одного файла

Образец средства выбора файлов показывает, как использовать 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"]);

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

Полный код выбора нескольких файлов см. в разделе Пример средства выбора файлов.

Пошаговый разбор выбора одного файла

Для вызова средства выбора файлов требуется выполнить две основные задачи: создание и настройка объекта средства выбора файлов и отображение средства выбора файлов, чтобы пользователь мог выбрать элементы.

Создание и настройка fileOpenPicker

Если пользователь выбирает один или несколько файлов, используйте fileOpenPicker. Данный класс можно настроить, задав свойства создаваемого объекта.

В образце средства выбора файлов показано, как создать и настроить объект 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"]);
```
Следует задать свойства объекта средства выбора файлов, соответствующие вашим пользователям и приложению. Указания по выбору настроек средства выбора файлов см. в разделе Указания и контрольный список для средств выбора файлов. Пояснения по выбору определенных свойств для настройки средств выбора файлов см. далее в разделе Образец средства выбора файлов.

Пояснения настроек образца средства выбора файлов fileOpenPicker

Образец средства выбора файлов создает сложное визуальное отображение в виде картинок в подходящем месте, которое пользователь может выбрать, установив три свойства fileOpenPicker: viewMode, suggestedStartLocation и fileTypeFilter.
- Установка openPicker.viewMode значений перечисления thumbnail PickerViewMode создает сложное визуальное отображение за счет эскизов картинок, представляющих файлы в средстве выбора файлов.
```
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
  Следует рассмотреть возможность установки для viewMode значения PickerViewMode.thumbnail в случае использования средства выбора файлов для отображения визуальных файлов, например изображений или видеозаписей. В других случаях воспользуйтесь PickerViewMode.list.
  
  Периодически пользователи желают выбрать изображение, видеозапись или файл другого типа. Например, пользователь может выбирать файл для прикрепления к сообщению электронной почты или для отправки через систему мгновенной передачи сообщений (IM). В этом случае следует обеспечить поддержку обоих режимов просмотра за счет добавления в ваше приложение двух элементов пользовательского интерфейса. Один элемент управления должен вызывать средство выбора файлов при помощи режима просмотра thumbnail, обеспечивая пользователю возможность выбора изображений и видеозаписей. Второй элемент управления должен вызывать средство выбора файлов при помощи режима просмотра list, обеспечивая пользователю возможность выбора файлов других типов. Например, почтовое приложение может иметь две кнопки: Прикрепить изображение или видеозапись и Прикрепить документ.
- Установка openPicker.suggestedStartLocation на библиотеку "Изображения" при помощи PickerLocationId.picturesLibrary позволяет пользователю начать работу в расположении вероятного нахождения изображений.
```
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
```
  Следует установить suggestedStartLocation на расположение в файловой системе, соответствующее типу выбираемого файла. При выборе пользователем музыки, изображений или видеозаписей установите начальное расположение на библиотеки "Музыка", "Изображения" или "Видео" соответственно. Для всех остальных типов файлов установите начальное расположение на библиотеку "Документы". Это лишь начальное расположение. Пользователи могут переходить к другим расположениям в процессе использования средства выбора файлов.
  
  Кроме того, suggestedStartLocation не всегда используется как начальное расположение для средства выбора файлов. Чтобы сформировать у пользователя чувство целостности, средство выбора файлов запоминает последнее расположение, просмотренное пользователем, и всегда начинает работу с него.
- Использование openPicker.fileTypeFilter.replaceAll для указания типов файлов, которые пользователь может увидеть в средстве выбора файлов, позволяет удерживать внимание пользователя на выборе файлов, пригодных для дальнейшего использования.
```
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
```
  Следует учитывать, какие именно типы файлов указаны для отображения в средстве выбора файлов, чтобы отображать их правильно. Например, если ваше приложение является проигрывателем видео, вы можете использовать свойство fileTypeFilter для обеспечения отображения файлов в средстве выбора файлов (при их поддержке вашим проигрывателем) на основе расширения имени видеофайла.
  
  Чтобы добавить типы файлов в fileTypeFilter вместо замены записей, можно использовать метод append вместо replaceAll.
Отображение fileOpenPicker

Вы можете показать средство выбора файлов, чтобы пользователь мог выбрать либо один, либо несколько файлов:
- Показ для выбора пользователем одного файла
  
  После создания и настройки средства выбора файлов пользователь может выбрать один файл, вызвав fileOpenPicker.pickSingleFileAsync. Когда пользователь выбирает файл, fileOpenPicker.pickSingleFileAsync возвращает объект storageFile, представляющий выбранный файл.
  
  Образец средства выбора файлов демонстрирует, как отобразить средство выбора файлов, чтобы позволить пользователю выбрать один файл, и как захватить выбранный файл для обработки.
```
// 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");
    }
});
```
  Когда вызов openPicker.pickSingleFileAsync завершается, выбранный файл, представленный объектом storageFile, передается литералу функции на обработку как параметр file. Если операция отменяется и элемент не выбирается, то этот параметр будет иметь значение null.
- Показ для выбора пользователем нескольких файлов
  
  После создания и настройки средства выбора файлов пользователь может выбрать несколько файлов, вызвав fileOpenPicker.pickMultipleFilesAsync.
  
  Когда пользователь выбирает несколько файлов, fileOpenPicker.pickMultipleFilesAsync возвращает список объектов storageFile, представляющих выбранные файлы.
  
  Образец средства выбора файлов демонстрирует, как показать средство выбора файлов, чтобы пользователь мог выбрать несколько файлов, и как захватить список выбранных файлов для обработки.
```
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");
    }
});
```
  После завершения вызова openPicker.pickMultipleFilesAsync список выбранных файлов передается в литерал функции для обработки в виде параметра files. Выбранные файлы в этом списке представлены объектами storageFile. Если операция отменяется и элемент не выбирается, то этот параметр будет иметь размер больше 0.

Полный код для выбора одной папки

Образец средства выбора файлов показывает, как использовать folderPicker для обеспечения пользователю возможности выбора одной папки.

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

Пошаговый разбор выбора одной папки

Для вызова средства выбора файлов требуется выполнить две основные задачи: создать и настроить объект средства выбора файлов и отобразить средство выбора файлов, чтобы пользователь мог выбрать элементы.

Создание и настройка folderPicker

В случае выбора папки пользователем воспользуйтесь folderPicker. Данный класс можно настроить, задав свойства создаваемого объекта.

В образце средства выбора файлов показано, как создать и настроить объект 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"]);
```
Следует задать свойства объекта средства выбора файлов, соответствующие вашим пользователям и приложению. Указания по выбору настроек средства выбора файлов см. в разделе Указания и контрольный список для средств выбора файлов. Пояснения по выбору определенных свойств для настройки средств выбора файлов см. далее в разделе Образец средства выбора файлов.

Пояснения настроек образца средства выбора файлов folderPicker

Образец средства выбора файлов настраивает средство выбора файлов на выбор папок, используя три свойства folderPicker: viewMode, suggestedStartLocation и fileTypeFilter.
- Использование значения по умолчанию PickerViewMode.list для folderPicker.viewMode позволяет создавать отображение наподобие списка в средстве выбора файлов. Данный список хорошо подходит для выбора не очень наглядных файлов, например документов.
  
  Следует рассмотреть возможность установки для viewMode значения PickerViewMode.thumbnail в случае использования средства выбора файлов для отображения визуальных файлов, например изображений или видеозаписей. В других случаях воспользуйтесь PickerViewMode.list.
  
  При отображении визуальных файлов наподобие изображений или видеозаписей следует установить для folderPicker.viewMode значение thumbnail следующим образом:
```
folderPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
```
- Установка folderPicker.suggestedStartLocation на компьютер пользователя с применением PickerLocationId.desktop позволяет пользователю начать работу со знакомого и часто используемого расположения.
```
folderPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.desktop;
```
  Следует установить suggestedStartLocation на расположение в файловой системе, соответствующее типу выбираемой пользователем папки. Например, при выборе пользователем папки, содержащей файлы с музыкой, следует начать с библиотеки "Музыка". Это лишь начальное расположение. Пользователи могут переходить к другим расположениям в процессе использования средства выбора файлов.
  
  Кроме того, suggestedStartLocation не всегда используется как начальное расположение для средства выбора файлов. Чтобы сформировать у пользователя чувство целостности, средство выбора файлов запоминает последнее расположение, просмотренное пользователем, и всегда начинает работу с него.
- Использование folderPicker.fileTypeFilter.replaceAll для указания типов файлов, которые пользователь может увидеть в средстве выбора файлов, позволяет удерживать внимание пользователя на выборе соответствующей папки.
```
folderPicker.fileTypeFilter.replaceAll([".docx", ".xlsx", ".pptx"]);
```
  Посредством folderPicker пользователи могут лишь выбирать папки, но не способны выбирать отдельные файлы. Однако отображение соответствующих файлов в folderPicker помогает пользователям определить, какую папку они желают выбрать. Например, при использовании folderPicker для выбора расположения импорта изображения отображение файлов изображений помогает пользователю определить, какие элементы должны быть импортированы после выбора расположения.
Показ folderPicker для выбора пользователем одной папки

После создания и настройки folderPicker пользователь может выбрать папку, вызвав folderPicker.pickSingleFolderAsync. Когда пользователь выбирает папку, folderPicker.pickSingleFolderAsync возвращает storageFolder, представляющий выбранную папку. Перехват и обработку исключений для этой папки необходимо выполнять с помощью done, чтобы обеспечить правильное распространение исключений.

Образец средства выбора файлов демонстрирует, как отобразить средство выбора файлов, чтобы позволить пользователю выбрать папку, и как захватить выбранную папку для обработки.
```
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");
    }
});
```
После завершения вызова folderPicker.pickSingleFolderAsync выбранная папка передается в литерал функции для обработки в виде параметра folder. Выбранная папка представляется объектом storageFolder. Если операция отменяется и элемент не выбирается, то этот параметр будет иметь значение null.

Краткая сводка и дальнейшие действия

Если вы используете код, аналогичный показанному здесь, ваше приложение будет отображать пользователям средство выбора файлов, позволяющее им выбрать один или несколько файлов или папок, которые ваше приложение может впоследствии открыть.

Совет При каждом доступе вашего приложения к файлу или папке через средство выбора файлов добавляйте этот элемент в свойство приложения futureAccessList или mostRecentlyUsedList для отслеживания. Подробнее об использовании этих списков см. в разделе Отслеживание последних использованных файлов и папок.

Сведения о чтении и записи файлов см. в разделах Краткое руководство: чтение и запись файла и Образец доступа к файлу. Сведения о работе с файлами изображений см. в разделах Выбор и отображение изображения, Декодирование изображения и Использование BLOB-объекта для сохранения и загрузки примера содержимого.

Дополнительные сведения о вызове средства выбора файлов для сохранения файлов см. в разделе Сохранение файлов с помощью средства выбора файлов.

Сведения о настройке вашего приложения для предоставления другим приложениям файлов, места сохранения или обновлений файлов см. в разделе Краткое руководство: предоставление служб в средстве выбора файлов.