Введение в API файлов и записей каталогов

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

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

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

Для получения справочной документации по API файлов и записей каталогов посетите страницу справочника и её подстраницы.

Спецификация всё ещё разрабатывается и может быть изменена.

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

API файлов и записей каталогов является важным API по следующим причинам:

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

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

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

• API файлов и записей каталогов предлагает локальное хранилище для случаев использования, которые не решаются базами данных. Если вы хотите иметь большие изменяемые блоки данных, API файлов и записей каталогов является гораздо более эффективным решением для хранения, чем база данных.
• Хотя Firefox поддерживает хранение блобов для IndexedDB, Chrome в настоящее время не поддерживает (Chrome всё ещё реализует поддержку блобов в IndexedDB). Если вы нацеливаетесь на Chrome для своего приложения и хотите хранить блоки, API файлов и записей каталогов и App Cache являются вашими единственными вариантами. Однако хранилище AppCache не является локально изменяемым и не позволяет тонкого клиентского управления.
• В Chrome вы можете использовать API файлов и записей каталогов с API управления квотами, которое позволяет запросить больше хранилища и управлять квотой хранилища.

Вот несколько примеров того, как вы можете использовать API файлов и записей каталогов:

• Приложения с постоянным загрузчиком

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

• Игры или другие приложения с большим количеством медиа-ресурсов

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

• Редактор аудио или фото с автономным доступом или локальным кешем (отлично для производительности и скорости)

  • Приложение может записывать в файлы на месте (например, перезаписывая только теги ID3/EXIF, а не весь файл).

• Автономный проигрыватель видео

  • Приложение может загружать большие файлы (>1 ГБ) для последующего просмотра.
  • Приложение может получать доступ к частично загруженным файлам (так что вы можете посмотреть первую главу вашего DVD, даже если приложение всё ещё загружает остальную часть контента или если приложение не завершило загрузку, потому что вам нужно было бежать, чтобы успеть на поезд).

• Автономный клиент веб-почты

  • Клиент загружает вложения и сохраняет их локально.
  • Клиент кэширует вложения для последующей загрузки.

Прежде чем использовать API файлов и записей каталогов, вы должны понять несколько понятий.

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

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

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

Используйте временное хранилище для кэширования и постоянное хранилище для данных, которые вы хотите сохранить в вашем приложении — например, данные, созданные пользователем или уникальные данные.

Чтобы предотвратить использование веб-приложением всего диска, браузеры могут установить квоту для каждого приложения и распределять хранилище между веб-приложениями.

Способ предоставления или распределения места хранения и как вы можете управлять хранилищем зависят от браузера, поэтому вам необходимо проверить соответствующую документацию браузера. Например, Google Chrome позволяет временное хранилище помимо 5 МБ, требуемых в спецификациях, и поддерживает API управления квотами. Чтобы узнать больше о реализации Chrome, см. Управление автономным хранением HTML.

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

WebWorkers

Асинхронный API можно использовать в контексте документа или WebWorkers, в то время как синхронный API предназначен только для использования с WebWorkers.

Обратные вызовы

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

Глобальные методы асинхронных и синхронных API

Асинхронный API имеет следующие глобальные методы: requestFileSystem() и resolveLocalFileSystemURL(). Эти методы являются членами объекта window и глобальной области видимости worker. Синхронный API, с другой стороны, использует следующие методы: requestFileSystemSync() и resolveLocalFileSystemSyncURL(). Эти синхронные методы являются членами только глобальной области видимости worker, а не объекта window.

Синхронный API может быть проще для некоторых задач. Его прямая, упорядоченная модель программирования может сделать код более читабельным. Недостатком синхронного API является его взаимодействие с WebWorkers, которое имеет некоторые ограничения.

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

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

• fetch()
• API перетаскивания
• Web Workers (для синхронной версии API файлов и записей каталогов)
• Элемент input (для программатического получения списка файлов из элемента)

API файловой системы регистрозависимый и сохраняющий регистр.

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

Происхождение — это домен, протокол прикладного уровня и порт URL документа, где выполняется сценарий. Каждое происхождение имеет свой набор файловых систем.

Граница безопасности, накладываемая на файловую систему, предотвращает приложениям доступ к данным с другим происхождением. Это защищает частные данные, предотвращая доступ и удаление. Например, приложение или страница в http://www.example.com/app/ может получить доступ к файлам из http://www.example.com/dir/, потому что у них одинаковое происхождение, но не может получить доступ к файлам из http://www.example.com:8080/dir/ (разный порт) или https://www.example.com/dir/ (разный протокол).

Для предотвращения запуска вредоносных приложений с вредоносными исполняемыми файлами, вы не можете создавать исполняемые файлы внутри песочницы API «Файлы и записи каталогов».

Поскольку файловая система находится в песочнице, веб-приложение не может получить доступ к файлам другого приложения. Вы также не можете читать или записывать файлы в произвольную папку (например, «Мои изображения» и «Мои документы») на жёстком диске пользователя.

Вы не можете запустить своё приложение локально из file://. В этом случае браузер выдаст ошибки или ваше приложение завершится молча. Это ограничение также распространяется на многие API файлов, включая Blob и FileReader.

Для целей тестирования вы можете обойти это ограничение в Chrome, запустив браузер с флагом --allow-file-access-from-files. Используйте этот флаг только для этой цели.

В этом разделе определяются и объясняются термины, используемые в API «Файлы и записи каталогов».

blob

Аббревиатура от binary large object. Blob — это набор двоичных данных, хранящихся как один объект. Это универсальный способ ссылки на двоичные данные в веб-приложениях. Blob может быть изображением или аудиофайлом.

Blob

Blob (с большой буквы B) — это структура данных, которая является неизменяемой, что означает, что двоичные данные, на которые ссылается Blob, не могут быть изменены напрямую. Это делает Blobs предсказуемыми при передаче в асинхронные API.

постоянное хранилище

Постоянное хранилище — это хранилище, которое сохраняется в браузере, пока пользователь его не удалит или приложение его не удалит.

временное хранилище

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

• API «Файлы и записи каталогов»
• Чтение файлов в JavaScript (web.dev)