Исходная пробная версия 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.
• Приложения, которым необходимо уведомлять основной поток об изменениях файловой системы с рабочей или другой вкладки.
• Приложения, которые наблюдают за каталогом ресурсов, например, для автоматической оптимизации изображений.

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

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

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

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

Примечание. Общие подходы к заполнению поведения API File System Observer API посредством опроса см. в разделе Объяснение .

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

Инициализируйте наблюдателя файловой системы, вызвав 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 ): дескриптор, на который повлияло изменение файловой системы.
• relativePathComponents ( Array ): путь changedHandle относительно root .
• type (a String ): тип изменения. Возможны следующие типы:
  • "appeared" : файл или каталог был создан или перемещен в root .
  • "disappeared" : файл или каталог был удален или перемещен из root .
  • "modified" : файл или каталог был изменен.
  • "moved" : файл или каталог был перемещен в root .
  • "unknown" : это указывает на то, что было пропущено ноль или более событий. В ответ на это разработчикам следует опросить просматриваемый каталог.
  • "errored" : наблюдение больше не действительно. В этом случае вы можете прекратить наблюдение за файловой системой .
• relativePathMovedFrom ( Array , необязательно): прежнее местоположение перемещенного дескриптора. Доступно только в том случае, если type "moved" .

Примечание. В зависимости от операционной системы не обо всех событиях изменения можно сообщать с одинаковым уровнем детализации, например, когда содержимое каталога изменяется рекурсивно. В лучшем случае веб-сайт получит подробную запись об изменении, содержащую тип изменения и дескриптор затронутого пути. В худшем случае веб-сайт получает более общую запись об изменении (то есть type со значением "unknown" ), которая по-прежнему требует от веб-сайта перечисления каталога , чтобы выяснить, какой дочерний элемент был изменен. Это все еще улучшение по сравнению с опросом, поскольку перечисление каталогов может быть запущено по требованию из функции обратного вызова, вместо необходимости опроса изменений через определенные интервалы.

Примечание. В Windows "moved" события между каталогами не поддерживаются. О них сообщается как об "disappeared" из исходного каталога и "appeared" в целевом каталоге. О них сообщается как о "moved" , если источник и место назначения находятся в одном каталоге.

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

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

observer.unobserve(fileHandle);

Примечание. Во время пробной версии источника метод unobserve() не поддерживается. Используйте метод disconnect() в качестве обходного пути.

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

Чтобы прекратить наблюдение за файловой системой, отключите экземпляр 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
• Ошибка хрома

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

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