Teste de origem da API File System Observer

Thomas Steiner

As APIs File System Access e Origin Private File System permitem que os desenvolvedores acessem arquivos e diretórios no dispositivo do usuário. O primeiro permite que os desenvolvedores leiam e gravem no sistema de arquivos normal visível ao usuário, e o segundo abre um sistema de arquivos especial, oculto do sistema de arquivos do usuário, particular à origem de cada site e que oferece algumas vantagens de desempenho. Os desenvolvedores interagem com arquivos e diretórios em ambos os casos usando objetos FileSystemHandle, de maneira mais concreta, FileSystemFileHandle para arquivos e FileSystemDirectoryHandle para diretórios. Até agora, ser informado sobre mudanças em um arquivo ou diretório em qualquer um dos sistemas de arquivos exigia alguma forma de pesquisa e comparação do carimbo de data/hora lastModified ou até mesmo do conteúdo do arquivo.

A API File System Observer, em teste de origem do Chrome 129, muda isso e permite que os desenvolvedores sejam alertados automaticamente quando ocorrem mudanças. Este guia explica como ele funciona e como testar o recurso.

Casos de uso

Use a API File System Observer em apps que precisam ser informados sobre possíveis mudanças no sistema de arquivos assim que elas acontecerem.

  • Ambientes de desenvolvimento integrados (IDEs) baseados na Web que mostram uma representação da árvore do sistema de arquivos de um projeto.
  • Apps que sincronizam mudanças no sistema de arquivos com um servidor. Por exemplo, um arquivo de banco de dados SQLite.
  • Apps que precisam notificar a linha de execução principal sobre mudanças no sistema de arquivos de um worker ou outra guia.
  • Apps que observam um diretório de recursos, por exemplo, para otimizar imagens automaticamente.

Como usar a API File System Observer

Detecção de recursos

Para conferir se há suporte para a API File System Observer, execute um teste de recurso como no exemplo a seguir.

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

Inicializar um observador do sistema de arquivos

Inicialize um observador do sistema de arquivos chamando new FileSystemObserver() e fornecendo a ele uma função callback como argumento.

const observer = new FileSystemObserver(callback);

Começar a observar um arquivo ou diretório

Para começar a observar um arquivo ou diretório, chame o método assíncrono observe() da instância FileSystemObserver. Forneça a este método o FileSystemHandle do arquivo ou diretório selecionado como um argumento. Ao observar um diretório, há um argumento options opcional que permite escolher se você quer receber informações sobre mudanças no diretório de forma recorrente (ou seja, para o próprio diretório e todos os subdiretórios e arquivos contidos). A opção padrão é observar apenas o próprio diretório e os arquivos diretamente contidos.

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

A função de callback

Quando ocorrem mudanças no sistema de arquivos, uma função de callback é chamada com a mudança do sistema de arquivos records e o próprio observer como argumentos. Você pode usar o argumento observer para, por exemplo, desconectar o observador (consulte Parar de observar o sistema de arquivos) quando todos os arquivos em que você tem interesse forem excluídos.

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

O registro de alteração do sistema de arquivos

Cada registro de alteração do sistema de arquivos tem a estrutura a seguir. Todos os campos são somente leitura.

  • root (um FileSystemHandle): o handle transmitido à função FileSystemObserver.observe().
  • changedHandle (um FileSystemHandle): o identificador afetado pela mudança no sistema de arquivos.
  • relativePathComponents (um Array): o caminho do changedHandle em relação ao root.
  • type (uma String): o tipo de alteração. Os seguintes tipos são possíveis:
    • "appeared": o arquivo ou diretório foi criado ou movido para root.
    • "disappeared": o arquivo ou diretório foi excluído ou movido do root.
    • "modified": o arquivo ou diretório foi modificado.
    • "moved": o arquivo ou diretório foi movido dentro de root.
    • "unknown": indica que zero ou mais eventos foram perdidos. Os desenvolvedores devem pesquisar o diretório monitorado em resposta a isso.
    • "errored": a observação não é mais válida. Nesse caso, pare de observar o sistema de arquivos.
  • relativePathMovedFrom (um Array, opcional): o antigo local de um identificador movido. Disponível apenas quando o type é "moved".
.

Parar de observar um arquivo ou diretório

Para parar de observar um FileSystemHandle, chame o método unobserve(), transmitindo o handle como um argumento.

observer.unobserve(fileHandle);

Parar de observar o sistema de arquivos

Para parar de observar o sistema de arquivos, desconecte a instância FileSystemObserver da seguinte maneira.

observer.disconnect();

Teste a API

Para testar a API File System Observer localmente, defina a flag #file-system-observer em about:flags. Para testar a API com usuários reais, inscreva-se no teste de origem e siga as instruções do guia Testes de origem do Chrome. O teste de origem vai acontecer do Chrome 129 (11 de setembro de 2024) ao Chrome 134 (26 de fevereiro de 2025).

Demonstração

Confira a API File System Observer em ação na demonstração incorporada. Confira o código-fonte ou remixe o código de demonstração no Glitch. A demonstração cria, exclui ou modifica arquivos aleatoriamente em um diretório observado e registra a atividade na parte superior da janela do app. Em seguida, ele registra as mudanças à medida que elas ocorrem na parte de baixo da janela do app. Se isso acontecer em um navegador sem suporte à API File System Observer, confira uma captura de tela da demonstração.

Feedback

Se você tiver feedback sobre o formato da API File System Observer, comente sobre o problema 123 no repositório WhatWG/fs.

Agradecimentos

Este documento foi revisado por Daseul Lee, Nathan Memmott, Etienne Noël e Rachel Andrew.