Исходная пробная версия API File System Observer

Томас Штайнер

API доступа к файловой системе (File System Access API) и API приватной файловой системы Origin (Origin Private File System API ) позволяют разработчикам получать доступ к файлам и каталогам на устройстве пользователя. Первый позволяет разработчикам читать и записывать данные в обычную, видимую пользователю файловую систему, а второй открывает специальную, скрытую от пользователя файловую систему, которая является приватной для каждого сайта- источника и обеспечивает определённые преимущества в производительности. В обоих случаях разработчики взаимодействуют с файлами и каталогами через объекты FileSystemHandle , а именно, FileSystemFileHandle для файлов и FileSystemDirectoryHandle для каталогов. До сих пор для получения информации об изменениях файла или каталога в любой из файловых систем требовалось определённое количество опросов и сравнение метки времени lastModified или даже самого содержимого файла.

API File System Observer, доступный в пробной версии Chrome 129, меняет ситуацию и позволяет разработчикам автоматически получать уведомления об изменениях. В этом руководстве объясняется, как это работает и как попробовать эту функцию.

Варианты использования

Используйте API File System Observer в приложениях, которым необходимо сообщать о возможных изменениях файловой системы сразу же по мере их возникновения.

  • Интегрированные веб-среды разработки (IDE), которые отображают представление дерева файловой системы проекта.
  • Приложения, синхронизирующие изменения файловой системы с сервером. Например, файл базы данных SQLite.
  • Приложения, которым необходимо уведомлять основной поток об изменениях файловой системы из рабочего процесса или другой вкладки.
  • Приложения, которые отслеживают каталог ресурсов, например, для автоматической оптимизации изображений.
  • Опыт, который выигрывает от горячей перезагрузки, например, слайд-шоу на основе HTML, где перезагрузка запускается при изменении файла.

Как использовать API File System Observer

Обнаружение особенностей

Чтобы проверить, поддерживается ли API File System Observer, запустите тест функций, как показано в следующем примере.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

Инициализировать наблюдателя файловой системы

Инициализируйте File System Observer, вызвав new FileSystemObserver() и передав ему функцию callback в качестве аргумента.

const observer = new FileSystemObserver(callback);

Начать наблюдение за файлом или каталогом

Чтобы начать наблюдение за файлом или каталогом, вызовите асинхронный метод observe() экземпляра FileSystemObserver . Передайте этому методу FileSystemHandle выбранного файла или каталога в качестве аргумента. При наблюдении за каталогом есть необязательный аргумент options , позволяющий выбрать, хотите ли вы получать рекурсивные уведомления об изменениях в каталоге (то есть для самого каталога и всех содержащихся в нём подкаталогов и файлов). Параметр по умолчанию — наблюдать только за самим каталогом и непосредственно содержащимися в нём файлами.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

Функция обратного вызова

При изменении файловой системы вызывается функция обратного вызова, аргументами которой являются records об изменениях файловой системы и сам observer . Аргумент observer можно использовать, например, для отключения наблюдателя (см. раздел Остановка наблюдения за файловой системой ) после удаления всех интересующих вас файлов.

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

Запись об изменении файловой системы

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

  • root ( FileSystemHandle ): дескриптор, переданный функции FileSystemObserver.observe() .
  • changedHandle ( FileSystemHandle ): дескриптор, затронутый изменением файловой системы. Это поле будет иметь null для событий типа "errored" , "unknown" и "disappeared" . Чтобы узнать, какой файл или каталог исчез, используйте relativePathComponents .
  • relativePathComponents ( Array ): путь к changedHandle относительно root .
  • type ( String ): тип изменения. Возможны следующие типы:
    • "appeared" : файл или каталог был создан или перемещен в root .
    • "disappeared" : файл или каталог был удален или перемещен из root .
    • "modified" : файл или каталог был изменён.
    • "moved" : файл или каталог был перемещен в пределах root .
    • "unknown" : означает, что пропущено ноль или более событий. Разработчикам следует опросить отслеживаемый каталог в ответ на это.
    • "errored" : Наблюдение больше недействительно. В этом случае вы можете прекратить наблюдение за файловой системой . Это значение также будет отправлено при достижении максимального лимита наблюдений для каждого источника. Этот лимит зависит от операционной системы и неизвестен заранее. В этом случае сайт может решить повторить попытку, хотя нет гарантии, что операционная система освободила достаточно ресурсов. Другой случай, когда это значение будет отправлено, — это удаление или перемещение наблюдаемого дескриптора (то есть корня наблюдения). В этом случае сначала отправляется событие "disappeared" , а затем событие "errored" , указывающее на то, что наблюдение больше недействительно. Наконец, это событие отправляется при удалении разрешения на доступ к каталогу или дескриптору файла.
  • relativePathMovedFrom ( Array , необязательный): предыдущее местоположение перемещённой ручки. Доступно только для type "moved" .

Остановить наблюдение за файлом или каталогом

Чтобы прекратить наблюдение за FileSystemHandle , вызовите метод unobserve() , передав ему дескриптор в качестве аргумента.

observer.unobserve(fileHandle);

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

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

observer.disconnect();

Попробуйте API

Чтобы протестировать API File System Observer локально, установите флаг #file-system-observer в about:flags . Чтобы протестировать API с реальными пользователями, зарегистрируйтесь в пробной версии Origin и следуйте инструкциям из руководства Chrome Origin Trials . Пробная версия Origin будет доступна с Chrome 129 (11 сентября 2024 г.) по Chrome 134 (26 февраля 2025 г.).

Демо

Вы можете увидеть API File System Observer в действии во встроенной демо-версии . Ознакомьтесь с исходным кодом . Демо-версия случайным образом создаёт, удаляет или изменяет файлы в наблюдаемом каталоге и регистрирует свою активность в верхней части окна приложения. Затем она регистрирует изменения по мере их возникновения в нижней части окна приложения. Если вы читаете это в браузере, который не поддерживает API File System Observer, посмотрите скриншот демо-версии.

Обратная связь

Если у вас есть отзывы о форме API File System Observer, прокомментируйте проблему № 123 в репозитории WHATWG/fs .

Благодарности

Этот документ был проверен Дасеулом Ли , Натаном Меммотом , Этьеном Ноэлем и Рэйчел Эндрю .