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

Thomas Steiner

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

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

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

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

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

Как использовать API наблюдателя файловой системы

Обнаружение функций

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

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

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

Инициализируйте наблюдателя файловой системы, вызвав 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 (a 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 в действии во встроенной демонстрации . Ознакомьтесь с исходным кодом или сделайте ремикс демо-кода на Glitch. Демо-версия случайным образом создает, удаляет или изменяет файлы в наблюдаемом каталоге и регистрирует свою активность в верхней части окна приложения. Затем он регистрирует изменения по мере их возникновения в нижней части окна приложения. Если вы читаете это в браузере, который не поддерживает API File System Observer, посмотрите скриншот демо-версии.

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

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

Соответствующие ссылки

• Объяснитель
• Обзор тегов
• Позиция Mozilla по стандартам
• Позиция по стандартам WebKit
• ChromeStatus
• Ошибка хрома

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

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