Teste de origem da API File System Observer

Thomas Steiner

A API File System Access e a API 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 gravassem no sistema de arquivos normal visível para o usuário, e o segundo abre um sistema de arquivos especial e oculto do usuário, que é particular para a origem de cada site e tem certas vantagens de desempenho. A maneira como os desenvolvedores interagem com arquivos e diretórios em ambos os casos é por objetos FileSystemHandle, mais especificamente, FileSystemFileHandle para arquivos e FileSystemDirectoryHandle para diretórios. Até agora, para receber informações sobre mudanças em um arquivo ou diretório em qualquer um dos sistemas de arquivos, era necessário fazer uma pesquisa e comparar o carimbo de data/hora lastModified ou até mesmo o 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 as mudanças acontecerem. Neste guia, explicamos 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 acontecem.

• 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 de outra guia.
• Apps que observam um diretório de recursos, por exemplo, para otimizar imagens automaticamente.
• Experiências que se beneficiam da recarga automática, como apresentações de slides baseadas em HTML, em que uma recarga é acionada por uma mudança de arquivo.

Como usar a API File System Observer

Detecção de recursos

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

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

Observação: consulte o texto explicativo para conferir abordagens gerais de preenchimento de polilinhas do comportamento da API File System Observer por meio de pesquisa.

Inicializar um observador do sistema de arquivos

Inicialize um observador do sistema de arquivos chamando new FileSystemObserver() e fornecendo 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 observe() assíncrono da instância FileSystemObserver. Forneça a esse 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 ser informado sobre mudanças no diretório de forma recursiva, ou seja, para o próprio diretório e todos os subdiretórios e arquivos contidos. A opção padrão é observar apenas o 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 de sistema de arquivos records e o observer como argumentos. É possível usar o argumento observer para, por exemplo, desconectar o observador (consulte Interromper a observação do sistema de arquivos) quando todos os arquivos de interesse forem excluídos.

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

O registro de mudança do sistema de arquivos

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

• root (um FileSystemHandle): o identificador transmitido para a função FileSystemObserver.observe().
• changedHandle (um FileSystemHandle): o identificador afetado pela mudança do sistema de arquivos. Esse campo será null para eventos do tipo "errored", "unknown" e "disappeared". Para saber qual arquivo ou diretório desapareceu, use relativePathComponents.
• relativePathComponents (um Array): o caminho do changedHandle em relação ao root.
• type (um String): o tipo de mudança. Os seguintes tipos são possíveis:
  • "appeared": o arquivo ou diretório foi criado ou movido para o root.
  • "disappeared": o arquivo ou diretório foi excluído ou removido do root.
  • "modified": o arquivo ou diretório foi modificado.
  • "moved": o arquivo ou diretório foi movido dentro do root.
  • "unknown": indica que zero ou mais eventos foram perdidos. Os desenvolvedores precisam consultar 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. Esse valor também será enviado quando o limite máximo de observações por origem for atingido. Esse limite depende do sistema operacional e não é conhecido de antemão. Se isso acontecer, o site pode tentar novamente, mas não há garantia de que o sistema operacional tenha liberado recursos suficientes. Outro caso em que esse valor será enviado é quando o identificador observado (ou seja, a raiz da observação) for excluído ou movido. Nesse caso, o evento "disappeared" é enviado primeiro, seguido por um evento "errored", indicando que a observação não é mais válida. Por fim, esse evento é enviado quando a permissão para o diretório ou o identificador de arquivo é removida.
• relativePathMovedFrom (um Array, opcional): o local anterior de uma alça movida. Disponível apenas quando type é "moved".

Observação: dependendo do sistema operacional, nem todos os eventos de mudança podem ser informados com o mesmo nível de detalhes, por exemplo, quando o conteúdo de um diretório muda de forma recursiva. Na melhor das hipóteses, o site vai receber um registro de mudança detalhado contendo o tipo de mudança e um identificador para o caminho afetado. Na pior das hipóteses, o site recebe um registro de mudança mais genérico (ou seja, um type com o valor "unknown") que ainda exige que o site enumere o diretório para descobrir qual filho mudou. Isso ainda é uma melhoria em relação à pesquisa, já que a enumeração de diretórios pode ser iniciada sob demanda pela função de callback, em vez de precisar pesquisar por mudanças em intervalos.

Observação: no Windows, não há suporte para eventos "moved" entre diretórios. Eles são informados como "disappeared" no diretório de origem e "appeared" no diretório de destino. Eles são informados como "moved" quando a origem e o destino estão no mesmo diretório.

Parar de observar um arquivo ou diretório

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

observer.unobserve(fileHandle);

Observação: o método unobserve() não é compatível. Use o método disconnect() como solução alternativa. Se você tiver interesse no progresso desse recurso, dê estrela ao bug do recurso.

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 conforme o guia Testes de origem do Chrome. O teste de origem vai ser executado 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 de cima da janela do app. Em seguida, ele registra as mudanças conforme elas ocorrem na parte de baixo da janela do app. Se você estiver lendo este artigo em um navegador que não oferece suporte à API File System Observer, consulte uma captura de tela da demonstração.

Feedback

Se você tiver feedback sobre a forma da API File System Observer, comente sobre a Questão 123 no repositório WHATWG/fs.

Links relevantes

• Explicação
• Análise da TAG
• Posição da Mozilla sobre padrões
• Posição do WebKit Standards
• ChromeStatus
• Bug do Chromium

Agradecimentos

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