Веб-приложения теперь могут взаимодействовать с вашей файловой системой – CloudSavvy IT

API доступа к файловой системе – это новая функция браузера, которая позволяет веб-сайтам и приложениям напрямую взаимодействовать с файловой системой вашего устройства. Есть сейчас частичная поддержка для API в последних версиях Chrome и Opera.

Что теперь API доступа к файловой системе раньше назывался API собственной файловой системы. Это была долгая разработка, включающая несколько раундов итераций для решения проблем безопасности. Эта функция была включена в стабильном выпуске из Chrome 86.

Обзор

Поддержка файлов в Интернете исторически ограничивалась выбором файла с вашего устройства с помощью <input type="file">. Невозможно писать напрямую в файловую систему пользователя с использованием предыдущих API. Вы должны использовать ссылки для скачивания, если вам нужно предоставить файл пользователю.

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

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

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

Как и большинство современных API-интерфейсов JavaScript, доступ к файловой системе является асинхронным. Вызовы его поверхности API возвращают Обещания. Самый чистый способ употребления – через async/await синтаксис ES7, который мы будем использовать в следующих примерах.

Чтение файла

Чтобы прочитать файл, вы открываете средство выбора файлов, используя window.showOpenFilePicker() функция. Нет необходимости использовать HTML <input type="file"> элемент.

Операционная система пользователя отобразит собственное средство выбора файлов. Как только пользователь выберет файл, возвращенное обещание будет разрешено с массивом FileSystemFileHandle объекты.

Чтобы получить содержимое файла, вызовите getFile() метод дескриптора файла. Это возвращает File объект, что вы получаете при работе с подборщиком файлов HTML. Как только у вас будет File, вы можете использовать его методы больших двоичных объектов, такие как text() и stream() читать его данные.

const [fileHandle] = await window.showOpenFilePicker();
const file = await file.getFile();
const fileData = await file.text();
console.log(fileData);

window.showOpenFilePicker() принимает объект параметров как единственный параметр. Вы можете разрешить пользователю выбирать несколько файлов, установив multiple вариант. Чтобы ограничить пользователя определенными типами файлов, передайте types вариант с массивом объектов, описывающих разрешенные типы. Каждый объект типа должен содержать description и accept свойства, которые определяют метку средства выбора файла типа и допустимые типы MIME соответственно.

const files = await window.showOpenFilePicker({
    multiple: true,
    types: [
        {
            description: "Image Files",
            accept: ["image/jpeg", "image/png"]
        }
    ]
});
 
for await (file of files) {
    const fileData = await file.getFile();
    console.log(fileData);
}

Параметр «все файлы» обычно отображается как допустимый тип файла, даже если types опция установлена. Вы можете отключить переопределение всех файлов, установив excludeAcceptAllOption вариант.

Запись в файл

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

Вот как заменить содержимое дескриптора файла, полученного из showOpenFilePicker():

// User selects a file
const fileHandle = await window.showOpenFilePicker();
 
// Get a `FileSystemWritableFileStream` we can write to
const writableFileStream = await fileHandle.createWritable();
 
// Write new file contents into the stream
await writableFileStream.write("Hello World");
 
// Close the writable stream - its content is now persisted to the file on disk
await writableFileStream.close();

Вызов write() в доступном для записи потоке вставляет текст в текущую позицию курсора в потоке. Чтобы изменить положение курсора, вызовите seek() метод, передающий новую позицию курсора. Третий метод для записываемых потоков – truncate(), который изменяет размер файла до максимального размера в байтах, который вы должны указать.

Иногда вам нужно будет записать в новый файл. Вы можете сделать это, попросив пользователя выбрать новое место для файла, используя window.showSaveFilePicker(). Это работает аналогично window.showOpenFilePicker() – возвращает FileHandle который вы затем сможете позвонить createWritable() на, чтобы получить доступный для записи поток.

const fileHandle = await window.showSaveFilePicker();
const writable = await fileHandle.createWritable();
await writable.write("Hello World");
await writable.close();

Вы можете использовать excludeAcceptAllOption и types варианты с window.showSaveFilePicker(). Они работают так же, как и их showOpenFilePicker() аналоги.

Справочники

API доступа к файловой системе также предоставляет каталоги. Пользователю может быть предложено выбрать каталог с помощью window.showDirectoryPicker(). Эта функция не принимает параметров. Он возвращает обещание, которое разрешится с помощью FileSystemDirectoryHandle представляющий каталог.

Вы можете перечислить содержимое каталога, перебирая его values(). Значения будут экземплярами дескрипторов файла или каталога.

const directoryHandle = window.showDirectoryPicker();
for await (let handle of directoryHandle.values()) {
    if (handle.type === "file") {
        // file
    }
    if (handle.type === "directory") {
        // subdirectory
    }
}

Если вы знаете имя файла или подкаталога, который ищете, вы можете использовать getFileHandle() или же getDirectoryHandle() методы для его получения. Оба эти метода принимают объект параметров, который в настоящее время имеет одно свойство, create. Установив это на true приведет к тому, что запрошенный файл или каталог будет автоматически создан в файловой системе, если он еще не существует.

Вы можете удалить файлы и папки из каталога с помощью removeEntry() в дескрипторе каталога. Принимает относительное имя удаляемого файла или подкаталога. При удалении каталога вы можете дополнительно установить recursive возможность также удалить его содержимое.

await directoryHandle.removeEntry("file.txt");
await directoryHandle.removeEntry("Subdirectory", {recursive: true});

Разрешения

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

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

Вы можете проверить, есть ли у вас еще разрешение на использование дескриптора, вызвав его queryPermission() метод:

const mode = "read";    // may also be "readwrite"
if (await fileHandle.queryPermission({mode}) === "granted") {
    // OK
}

Когда вам нужно повторно запросить разрешение, используйте requestPermission() метод таким же образом.

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

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

Вывод

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

Независимо от того, создаете ли вы текстовый редактор, фотогалерею или бизнес-приложение, возможность взаимодействия с файловой системой устройства дает вам новые возможности. Хотя в ближайшем будущем поддержка браузером будет ограничена Chrome и Opera (Mozilla рассматривает API как «Потенциально очень опасно»), Доступ к файловой системе помогает развить Интернет как платформу приложений и еще больше сокращает разрыв между Интернетом и собственными приложениями.