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

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

Thomas Steiner

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

File System Observer API, в пробной версии от 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 (a String ): Тип изменения. Возможны следующие типы:
- "appeared" : файл или каталог был создан или перемещен в root .
- "disappeared" : файл или каталог был удален или перемещен из root .
- "modified" : файл или каталог был изменен.
- "moved" : файл или каталог был перемещен в пределах root .
- "unknown" : Это означает, что было пропущено ноль или более событий. Разработчики должны опросить отслеживаемый каталог в ответ на это.
- "errored" : наблюдение больше не действительно. В этом случае вы можете прекратить наблюдение за файловой системой . Это значение также будет отправлено, когда будет достигнут максимальный предел наблюдений для каждого источника. Этот предел зависит от операционной системы и заранее неизвестен. Если это произойдет, сайт может решить повторить попытку, хотя нет гарантии, что операционная система освободила достаточно ресурсов. Другой случай, когда это значение будет отправлено, — это когда наблюдаемый дескриптор (то есть корень наблюдения) удален или перемещен. В этом случае сначала отправляется событие "disappeared" , за которым следует событие "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, оставьте комментарий к Issue #123 в репозитории WHATWG/fs .

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

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

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