Зарегистрируйте приложение в качестве обработчика файлов в операционной системе.
Теперь, когда веб-приложения способны читать и записывать файлы , следующим логическим шагом будет разрешение разработчикам объявлять эти самые веб-приложения в качестве обработчиков файлов, которые их приложения могут создавать и обрабатывать. API обработки файлов позволяет вам сделать именно это. После регистрации приложения текстового редактора в качестве обработчика файлов и его установки вы можете щелкнуть правой кнопкой мыши файл .txt
в macOS и выбрать «Получить информацию», чтобы затем указать ОС, что она всегда должна открывать файлы .txt
с этим приложением по умолчанию. .
Предлагаемые варианты использования API обработки файлов
Примеры сайтов, которые могут использовать этот API:
- Приложения Office, такие как текстовые редакторы, приложения для работы с электронными таблицами и средства создания слайд-шоу.
- Графические редакторы и инструменты рисования.
- Инструменты для редактирования уровней видеоигр.
Как использовать API обработки файлов
Прогрессивное улучшение
API обработки файлов сам по себе не может быть заполнен полифилом. Однако функциональность открытия файлов с помощью веб-приложения может быть достигнута двумя другими способами:
- API-интерфейс Web Share Target позволяет разработчикам указывать свое приложение в качестве общего ресурса, чтобы файлы можно было открывать из общего списка операционной системы.
- API доступа к файловой системе может быть интегрирован с функцией перетаскивания файлов, поэтому разработчики могут обрабатывать удаленные файлы в уже открытом приложении.
Поддержка браузера
Обнаружение функций
Чтобы проверить, поддерживается ли API обработки файлов, используйте:
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
// The File Handling API is supported.
}
Декларативная часть API обработки файлов
В качестве первого шага веб-приложениям необходимо декларативно описать в манифесте своего веб-приложения, какие файлы они могут обрабатывать. API обработки файлов расширяет манифест веб-приложения новым свойством "file_handlers"
, которое принимает массив обработчиков файлов. Обработчик файла — это объект со следующими свойствами:
- Свойство
"action"
адрес в области приложения в качестве своего значения. - Свойство
"accept"
с объектом MIME-типов в качестве ключей и списками расширений файлов в качестве их значений. - Свойство
"icons"
с массивом значковImageResource
. Некоторые операционные системы позволяют ассоциации типов файлов отображать значок, который является не просто значком связанного приложения, а специальным значком, связанным с использованием этого типа файла в приложении. - Свойство
"launch_type"
, которое определяет, следует ли открывать несколько файлов в одном клиенте или в нескольких клиентах. По умолчанию используется"single-client"
. Если пользователь открывает несколько файлов и если обработчик файлов помечен как"multiple-clients"
в качестве"launch_type"
, произойдет более одного запуска приложения, и для каждого запуска будет создан массивLaunchParams.files
(см . ниже ). иметь только один элемент.
Пример ниже, показывающий только соответствующий фрагмент манифеста веб-приложения, должен прояснить ситуацию:
{
"file_handlers": [
{
"action": "/open-csv",
"accept": {
"text/csv": [".csv"]
},
"icons": [
{
"src": "csv-icon.png",
"sizes": "256x256",
"type": "image/png"
}
],
"launch_type": "single-client"
},
{
"action": "/open-svg",
"accept": {
"image/svg+xml": ".svg"
},
"icons": [
{
"src": "svg-icon.png",
"sizes": "256x256",
"type": "image/png"
}
],
"launch_type": "single-client"
},
{
"action": "/open-graf",
"accept": {
"application/vnd.grafr.graph": [".grafr", ".graf"],
"application/vnd.alternative-graph-app.graph": ".graph"
},
"icons": [
{
"src": "graf-icon.png",
"sizes": "256x256",
"type": "image/png"
}
],
"launch_type": "multiple-clients"
}
]
}
Это для гипотетического приложения, которое обрабатывает файлы значений, разделенных запятыми ( .csv
), в /open-csv
, файлы масштабируемой векторной графики ( .svg
) в /open-svg
и искусственный формат файла Grafr с любым из .grafr
, .graf
или .graph
как расширение /open-graf
. Первые два откроются в одном клиенте, последний — в нескольких клиентах, если обрабатывается несколько файлов.
Обязательная часть API обработки файлов
Теперь, когда приложение теоретически заявило, какие файлы оно может обрабатывать и по какому URL-адресу в области видимости, ему необходимо обязательно что-то делать с входящими файлами на практике. Здесь в игру вступает launchQueue
. Для доступа к запускаемым файлам сайту необходимо указать потребителя для объекта window.launchQueue
. Запуски ставятся в очередь до тех пор, пока они не будут обработаны указанным потребителем, который вызывается ровно один раз для каждого запуска. Таким образом обрабатывается каждый запуск независимо от того, когда был указан потребитель.
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
launchQueue.setConsumer((launchParams) => {
// Nothing to do when the queue is empty.
if (!launchParams.files.length) {
return;
}
for (const fileHandle of launchParams.files) {
// Handle the file.
}
});
}
Поддержка инструментов разработчика
На момент написания этой статьи поддержка DevTools отсутствует, но я подал запрос на добавление поддержки.
Демо
Я добавил поддержку обработки файлов в Excalidraw , приложение для рисования в мультяшном стиле. Чтобы протестировать его, сначала необходимо установить Excalidraw. Когда вы затем создадите с его помощью файл и сохраните его где-нибудь в своей файловой системе, вы можете открыть файл двойным щелчком мыши или щелчком правой кнопкой мыши, а затем выбрать «Excalidraw» в контекстном меню. Вы можете проверить реализацию в исходном коде.
![Окно поиска macOS с файлом Excalidraw.](https://developer.chrome.com/static/docs/capabilities/web-apis/file-handling/image/the-macos-finder-window-eac9df1131965.png?authuser=5&hl=ru)
![Контекстное меню, которое появляется при щелчке правой кнопкой мыши по файлу с выделенным пунктом «Открыть с помощью… Excalidraw».](https://developer.chrome.com/static/docs/capabilities/web-apis/file-handling/image/the-context-menu-appears-76d8a48d9d84e.png?authuser=5&hl=ru)
.excalidraw
.Безопасность
Команда Chrome разработала и реализовала API обработки файлов, используя основные принципы, определенные в разделе «Управление доступом к мощным функциям веб-платформы» , включая пользовательский контроль, прозрачность и эргономику.
Разрешения, сохранение разрешений и обновления обработчиков файлов
Чтобы обеспечить доверие пользователей и безопасность файлов пользователей, когда API обработки файлов открывает файл, перед тем, как PWA сможет просмотреть файл, будет отображаться запрос разрешения. Этот запрос разрешения будет отображаться сразу после того, как пользователь выберет PWA для открытия файла, так что разрешение будет тесно связано с действием по открытию файла с помощью PWA, что сделает его более понятным и актуальным.
Это разрешение будет отображаться каждый раз, пока пользователь не нажмет « Разрешить» или «Блокировать обработку файлов для сайта» или не проигнорирует запрос три раза (после чего Chromium наложит эмбарго и заблокирует это разрешение). Выбранный параметр будет сохраняться при закрытии и повторном открытии PWA.
При обнаружении обновлений манифеста и изменений в разделе "file_handlers"
разрешения будут сброшены.
Проблемы, связанные с файлами
Существует большая категория векторов атак, которые открываются, предоставляя веб-сайтам доступ к файлам. Они описаны в статье об API доступа к файловой системе . Дополнительная возможность, связанная с безопасностью, которую API обработки файлов предоставляет по сравнению с API доступа к файловой системе, — это возможность предоставлять доступ к определенным файлам через встроенный пользовательский интерфейс операционной системы, а не через средство выбора файлов, отображаемое веб-приложением.
По-прежнему существует риск того, что пользователи могут непреднамеренно предоставить веб-приложению доступ к файлу, открыв его. Однако обычно понимается, что открытие файла позволяет приложению, с помощью которого он открыт, читать и/или манипулировать этим файлом. Таким образом, явный выбор пользователя открыть файл в установленном приложении, например, через контекстное меню «Открыть с помощью…», может быть расценен как достаточный сигнал доверия к приложению.
Проблемы обработчика по умолчанию
Исключением является случай, когда в хост-системе нет приложений для данного типа файлов. В этом случае некоторые операционные системы хоста могут автоматически повысить статус вновь зарегистрированного обработчика до обработчика по умолчанию для этого типа файла автоматически и без какого-либо вмешательства пользователя. Это будет означать, что если пользователь дважды щелкнет файл этого типа, он автоматически откроется в зарегистрированном веб-приложении. В таких хостовых операционных системах, когда пользовательский агент определяет, что для типа файла не существует обработчика по умолчанию, может потребоваться явный запрос разрешения, чтобы избежать случайной отправки содержимого файла в веб-приложение без согласия пользователя.
Пользовательский контроль
В спецификации говорится, что браузеры не должны регистрировать каждый сайт, который может обрабатывать файлы, в качестве обработчика файлов. Вместо этого регистрация обработки файлов должна осуществляться после установки и никогда не происходить без явного подтверждения пользователя, особенно если сайт должен стать обработчиком по умолчанию. Вместо того, чтобы перехватывать существующие расширения, такие как .json
, для которых у пользователя, вероятно, уже зарегистрирован обработчик по умолчанию, сайтам следует рассмотреть возможность создания собственных расширений.
Прозрачность
Все операционные системы позволяют пользователям изменять существующие ассоциации файлов. Это выходит за рамки браузера.
Обратная связь
Команда Chrome хочет услышать о вашем опыте работы с API обработки файлов.
Расскажите нам о дизайне API
Что-то в API работает не так, как вы ожидали? Или вам не хватает методов или свойств, необходимых для реализации вашей идеи? У вас есть вопрос или комментарий по модели безопасности?
- Сообщите о проблеме спецификации в соответствующем репозитории GitHub или добавьте свои мысли к существующей проблеме.
Сообщить о проблеме с реализацией
Вы нашли ошибку в реализации Chrome? Или реализация отличается от спецификации?
- Сообщите об ошибке на сайте new.crbug.com . Обязательно включите как можно больше подробностей, простые инструкции по воспроизведению и введите
UI>Browser>WebAppInstalls>FileHandling
в поле «Компоненты» . Glitch отлично подходит для быстрого и простого обмена репродукциями.
Показать поддержку API
Планируете ли вы использовать API обработки файлов? Ваша публичная поддержка помогает команде Chrome расставлять приоритеты для функций и показывает другим поставщикам браузеров, насколько важно их поддерживать.
- Поделитесь, как вы планируете его использовать, в теме обсуждения WICG .
- Отправьте твит @ChromiumDev , используя хэштег
#FileHandling
, и сообщите нам, где и как вы его используете.
Полезные ссылки
- Публичный объяснитель
- Демонстрация API обработки файлов | Демонстрационный исходный код API обработки файлов
- Ошибка отслеживания в Chrome
- Запись ChromeStatus.com
- Компонент Blink:
UI>Browser>WebAppInstalls>FileHandling
- Обзор тегов
- Позиция Mozilla по стандартам
Благодарности
API обработки файлов был указан Эриком Виллигерсом , Джеем Харрисом и Рэймсом Хури . Эта статья была рассмотрена Джо Медли .