Esta página foi traduzida pela API Cloud Translation.

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 regular visível para o usuário, e o segundo abre um sistema de arquivos especial, oculto do usuário, que é particular à origem de cada site e vem com certas vantagens de desempenho. Em ambos os casos, os desenvolvedores interagem com arquivos e diretórios usando objetos FileSystemHandle, mais especificamente, FileSystemFileHandle para arquivos e FileSystemDirectoryHandle para diretórios. Até agora, para saber 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 desde o Chrome 129, muda isso e permite que os desenvolvedores sejam alertados automaticamente quando ocorrem mudanças. 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 saber se a API File System Observer é compatível, 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 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 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, no próprio diretório e em todos os subdiretórios e arquivos contidos). A opção padrão é observar apenas o diretório e os arquivos contidos diretamente.

// 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 no 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 de seu 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 mudança no sistema de arquivos tem a seguinte estrutura. Todos os campos são somente leitura.

root (um FileSystemHandle): o identificador transmitido à função FileSystemObserver.observe().
changedHandle (um FileSystemHandle): o identificador afetado pela mudança no 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 root.
- "disappeared": o arquivo ou diretório foi excluído ou movido para fora 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, talvez seja melhor parar 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 antecipadamente. Se isso acontecer, o site poderá tentar novamente, mas não há garantia de que o sistema operacional liberou 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, primeiro o evento "disappeared" é enviado, 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 um identificador movido. Disponível apenas quando type é "moved".

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);

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 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. 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 conforme elas ocorrem na parte de baixo da janela do app. Se você estiver lendo isso em um navegador que não oferece suporte à API File System Observer, confira uma captura de tela da demonstração.

Feedback

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

Links relevantes

Agradecimentos

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