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 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. 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 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 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 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 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. É 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 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 identificador transmitido para a função FileSystemObserver.observe().
• changedHandle (um FileSystemHandle): o identificador afetado pela mudança do sistema de arquivos.
• 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 movido 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.
• 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 recursivamente. 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, os eventos "moved" não têm suporte entre diretórios. Eles são informados como um "disappeared" no diretório de origem e um "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: durante o teste de origem, o método unobserve() não é compatível. Como alternativa, use o método disconnect().

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.