Краткое руководство: доступ к файлам программными средствами (HTML)

Статья
12/12/2015

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

Получение файлов и папок из таких расположений, как папка, библиотека, устройство или расположение в сети. Для запроса файлов и папок из расположения можно также конструировать запросы файлов и папок.

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

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

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

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

Перечисление файлов и папок верхнего уровня в расположении

Получение объекта StorageFolder, представляющего расположение.

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

Пример перечисления папок демонстрирует, как получить библиотеку изображений.
```
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
```
В предыдущем примере мы используем KnownFolders, чтобы получить библиотеку изображений (как объект StorageFolder). Вы можете использовать свойства KnownFolders, чтобы получить папки, представляющие ресурсы пользователя, например библиотеки, устройства или сетевые размещения.

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

Пример перечисления папок демонстрирует, как получить список элементов в библиотеке изображений.
```
picturesLibrary.getItemsAsync().then(function (items) {
```
Как показано в предыдущем примере, вы можете вызывать getItemsAsync() для получения списка всего содержимого папки (объект StorageFolder). Если вам не нужны все элементы, то вы можете вызвать getItemsAsync(startIndex, maxItemsToRetrieve), чтобы получить содержимое папки в диапазоне индекса.

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

Если вам нужен список файлов в папке, вы можете вызывать метод getFilesAsync. Если вам нужен список папок, вы можете вызывать метод getFoldersAsync.

Используйте then после того, как вы получите операцию, чтобы определить функцию, выполняющую дополнительные нужные вам задачи со списком полученных вами объектов items в предыдущем примере.
Работа со списком.

Пример перечисления папок демонстрирует, как выполнять дополнительные задачи со списком items в библиотеке изображений.
```
    outputHeader(picturesLibrary.name, items.size);
    items.forEach(function (item) { 
        if (item.isOfType(Windows.Storage.StorageItemTypes.folder)) { 
            output(id(picturesLibrary.name), item.name + "\\"); 
        } 
        else { 
            output(id(picturesLibrary.name), item.fileName); 
        } 
    });
```
В предыдущем примере приложение передает name папки и size списка вспомогательной функции, отображающей эту информацию для пользователя.

Вы также можете повторить выполнение операции с элементами списка, чтобы выполнить дополнительные задачи, как показано в предыдущем примере. Для перебора элементов списка вы можете вызвать forEach в отношении вашего списка элементов. Функция, которую вы передаете forEach, должна принимать список элементов в качестве аргумента и будет выполняться для каждого элемента item в списке.

Вы можете дополнительно обработать каждый item, вызывая для них методы в индивидуальном порядке. В предыдущем примере мы определили, является ли item папкой (объект StorageFolder) или файлом (объект StorageFile), сравнив результат метода isOfType, присутствующего как в файлах, так и в папках, с перечисляемым значением StorageItemTypes. Мы используем это сравнение для передачи вспомогательной функции output различной информации об элементе, но вы можете выполнить и ряд дополнительных задач.

Для получения дополнительного контекста, а также чтобы увидеть, как работают функции outputHeader и output, скачайте Пример перечисления папок.

После этого ваш код должен выглядеть примерно так:


// Get folder
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;

//  Get folder contents
picturesLibrary.getItemsAsync().then(function (items) {
    // Then perform tasks with the list of files and folders that was retrieved

    // For example, display name of containing folder and count of items in folder
    outputHeader(picturesLibrary.name, items.size);

    // For example, display info for each item
    items.forEach(function (item) { 
        if (item.isOfType(Windows.Storage.StorageItemTypes.folder)) { 
            output(id(picturesLibrary.name), item.name + "\\"); 
        } 
        else { 
            output(id(picturesLibrary.name), item.fileName); 
        } 
    }); 
});

Запрос файлов из расположения.

Получение содержащей папки.

Если вы хотите получить список содержимого определенной папки, то сначала должны получить папку.

Пример перечисления папок демонстрирует, как получить библиотеку изображений.
```
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
```
В предыдущем примере мы используем KnownFolders, чтобы получить библиотеку изображений (как объект StorageFolder). Вы можете использовать свойства KnownFolders, чтобы получить папки, представляющие ресурсы пользователя, например библиотеки, устройства или сетевые размещения.

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

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

Пример перечисления папок демонстрирует, как создать запрос папки, группирующий изображения в библиотеке изображений по месяцам, в которые они были созданы или получены.
```
var query = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth);
```
Как показано в предыдущем примере, вы можете вызвать createFolderQuery(query) для вашей папки, чтобы создать запрос папки (объект StorageFolderQueryResult) для организации файлов в этой папке и подпапках в виртуальные папки на основании указанного вами значения CommonFolderQuery. В примере мы решаем группировать файлы изображений в папке picturesLibrary в виртуальные папки на основании месяца (CommonFolderQuery.groupByMonth), когда изображение было создано или получено.

Вы также можете создать запросы папок, вызвав createFolderQuery() или createFolderQueryWithOptions.
Получение списка виртуальных папок из запроса.

В примере FolderEnumeration на домашней странице примеров приложений для получения списка виртуальных папок используется query:
```
query.getFoldersAsync().then(function (monthList) {
    monthList.forEach(function (month) { 
```
Как показано в предыдущем примере, для получения списка виртуальных папок вы можете вызвать getFoldersAsync() для вашего запроса папки. Используйте then для определения функции, которая обрабатывает ваш список. В примере запрос возвращает список виртуальных папок, представляющих месяцы (monthList), и мы обрабатываем наш список, вызывая monthList.forEach и определяя функцию для обработки каждой папки month.
Получение списка файлов в виртуальной папке.

Пример перечисления папок демонстрирует, как использовать папку month для получения списка изображений, созданных или полученных в этом месяце.
```
        var tempMonthName = month.name; 
        month.getFilesAsync().then(function (files) {
```
Совет Вам может потребоваться сохранить информацию о своей виртуальной папке (month), чтобы ею можно было воспользоваться позднее. В предыдущем примере мы сохраняем имя виртуальной папки (month.name) в tempMonthName, чтобы ее можно было использовать при обработке нашего списка изображений (files).

Для определения функции, обрабатывающей получаемый вами список файлов, используйте then.

После этого ваш код должен выглядеть примерно так:


// Get folder
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary; 

// Create query
var query = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth); 

// Get virtual folders from query
query.getFoldersAsync().then(function (monthList) { 
    monthList.forEach(function (month) {
 
        var tempMonthName = month.name;
        // Get files from virtual folder 
        month.getFilesAsync().then(function (files) { 
            // Then perform tasks with retrieved files
        }); 
    }); 
});