Эта страница переведена с помощью Cloud Translation API.

Исходная пробная версия 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.
}

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

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

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

Чтобы прекратить наблюдение за 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 .

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

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

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