Aplicativos da web podem interagir com seu sistema de arquivos agora

A API de acesso ao sistema de arquivos é um novo recurso do navegador que permite que sites e aplicativos interajam diretamente com o sistema de arquivos do seu dispositivo. Agora há suporte parcial para a API nas versões recentes do Chrome e Opera.

O que agora é a API File System Access costumava ser conhecida como API Native File System. Ele teve um longo desenvolvimento envolvendo várias rodadas de iteração para tratar de questões de segurança. O recurso foi ativado na versão estável do Chrome 86.

Visão geral

O suporte a arquivos na web tem sido historicamente limitado à seleção de um arquivo de seu dispositivo usando < input type = "file" & gt ;. É impossível escrever diretamente no sistema de arquivos do usuário usando APIs anteriores. Você deve usar links de download se precisar fornecer um arquivo ao usuário.

A API de acesso ao sistema de arquivos fornece uma maneira para os sites obterem acesso de leitura e gravação ao sistema de arquivos do seu dispositivo. Isso torna possível criar novas classes de aplicativos da web complexos que interagem com seus arquivos. Editores de texto baseados na web, bibliotecas de fotos e players de mídia podem carregar conteúdo armazenado localmente em seu dispositivo.

Usando a API, você pode enumerar o conteúdo dos diretórios, ler dados de arquivos e gravar em arquivos novos e existentes armazenados no dispositivo do usuário. O acesso é fornecido por meio dos objetos de manipulação FileSystemFileHandle e FileSystemDirectoryHandle, que representam arquivos no sistema do usuário.

A API de acesso ao sistema de arquivos só pode ser usada em páginas carregadas em HTTPS. Ele está protegido por permissões com as quais o usuário deve consentir explicitamente. O usuário será solicitado a fornecer consentimento cada vez que usar a API. Isso usa o mesmo sistema de solicitações de permissão para outros recursos da web, como notificações e acesso à câmera.

Como a maioria das APIs JavaScript modernas, o File System Access é assíncrono. As chamadas para sua superfície de API retornam promessas. A maneira mais limpa de consumi-lo é por meio da sintaxe async / await do ES7, que é o que usaremos nos exemplos a seguir.

Lendo um arquivo

Para ler um arquivo, você abre um seletor de arquivos usando a função window. showOpenFilePicker (). Não há necessidade de usar o HTML < input type = "arquivo" > elemento.

O sistema operacional do usuário renderizará um seletor de arquivo nativo. Depois que o usuário seleciona um arquivo, a promessa retornada será resolvida com uma matriz de objetos FileSystemFileHandle.

Para obter o conteúdo do arquivo, chame o método getFile () do identificador de arquivo. Isso retorna um objeto File, que é o que você obtém ao trabalhar com um selecionador de arquivos HTML. Depois de ter o arquivo, você pode usar seus métodos de blob, como text () e stream () para ler seus dados.

const & # 91; fileHandle & # 93; = await window. showOpenFilePicker & # 40; & # 41 ;; const file = await file. getFile & # 40; & # 41 ;; const fileData = await file. text & # 40; & # 41 ;; console. log & # 40; fileData & # 41 ;;

window. showOpenFilePicker () aceita um objeto options como seu único parâmetro. Você pode permitir que o usuário selecione vários arquivos definindo a opção múltipla. Para restringir o usuário a tipos de arquivo específicos, passe a opção de tipos com uma série de objetos que descrevem os tipos permitidos. Cada objeto de tipo deve conter a descrição e aceitar as propriedades que determinam o rótulo do seletor de arquivo do tipo e os tipos MIME permitidos, respectivamente.

const files = await window. showOpenFilePicker & # 40; & # 123; múltiplo: verdadeiro, tipos: & # 91; & # 123; descrição: " Arquivos de imagem & quot ;, aceitar: & # 91; " image / jpeg ", " image / png " & # 93; & # 125; & # 93; & # 125; & # 41 ;;   para esperar & # 40; arquivo de arquivos & # 41; & # 123; const fileData = esperar arquivo. getFile & # 40; & # 41 ;; console. log & # 40; fileData & # 41 ;; & # 125;

Um “ todos os arquivos ” A opção normalmente é mostrada como um tipo de arquivo permitido, mesmo quando a opção de tipos está definida. Você pode desativar a substituição de todos os arquivos definindo a opção excludeAcceptAllOption.

Gravando em um arquivo

Assim que tiver um identificador de arquivo, você também pode escrever nele! Há outra camada de abstração com a qual lidar, pois você deve primeiro adquirir um FileSystemWritableFileStream. Este stream representa o arquivo e permite que você mantenha as gravações na memória até que elas sejam persistidas no disco.

Veja como substituir o conteúdo de um identificador de arquivo obtido em showOpenFilePicker ():

// O usuário seleciona um fileconst fileHandle = await window. showOpenFilePicker & # 40; & # 41 ;;   // Obtenha um `FileSystemWritableFileStream` que podemos escrever toconst writableFileStream = await fileHandle. createWritable & # 40; & # 41 ;;   // Grava novos conteúdos de arquivo no fluxo await writableFileStream. write & # 40; " Hello World " & # 41 ;;   // Fechar o fluxo gravável - seu conteúdo agora é mantido no arquivo no disco aguarda writableFileStream. close & # 40; & # 41 ;;

Chamar write () em um fluxo gravável irá inserir texto na posição atual do cursor no fluxo. Para alterar a posição do cursor, chame o método seek () passando a nova posição do cursor. Um terceiro método em fluxos graváveis ​​é truncate (), que redimensiona o arquivo para um tamanho máximo em bytes que você deve especificar.

Às vezes, você precisará gravar em um novo arquivo. Você pode fazer isso pedindo ao usuário para escolher um novo local para o arquivo usando window. showSaveFilePicker (). Isso funciona de forma semelhante a window. showOpenFilePicker () – ele retorna um FileHandle no qual você poderá então chamar createWritable () para obter um fluxo gravável.

const fileHandle = await window. showSaveFilePicker & # 40; & # 41 ;; const writable = await fileHandle. createWritable & # 40; & # 41 ;; aguarde writable. write & # 40; " Hello World " & # 41 ;; aguarde writable. close & # 40; & # 41 ;;

Você pode usar as opções excludeAcceptAllOption e types com window. showSaveFilePicker (). Eles funcionam de forma idêntica a suas contrapartes showOpenFilePicker ().

Diretórios

A API de acesso ao sistema de arquivos também expõe diretórios. O usuário pode ser solicitado a selecionar um diretório usando window. showDirectoryPicker (). Esta função não aceita parâmetros. Ele retorna uma promessa que será resolvida com um FileSystemDirectoryHandle representando o diretório.

Você pode enumerar o conteúdo do diretório iterando seus valores (). Os valores serão instâncias de identificador de arquivo ou diretório.

const directoryHandle = window. showDirectoryPicker & # 40; & # 41 ;; para await & # 40; let handle of directoryHandle. values ​​& # 40; & # 41; & # 41; & # 123; if & # 40; handle. type === " arquivo " & # 41; & # 123; // arquivo & # 125; if & # 40; handle. type === " diretório " & # 41; & # 123; // subdiretório & # 125; & # 125;

Se você souber o nome do arquivo ou subdiretório que está procurando, poderá usar os métodos getFileHandle () ou getDirectoryHandle () para recuperá-lo. Ambos os métodos aceitam um objeto de opções que atualmente possui uma única propriedade, criar. Definir isso como verdadeiro fará com que o arquivo ou diretório solicitado seja criado automaticamente dentro do sistema de arquivos, se ainda não existir.

Você pode excluir arquivos e pastas de um diretório usando o método removeEntry () em um identificador de diretório. Isso aceita o nome relativo do arquivo ou subdiretório a ser excluído. Ao excluir um diretório, você pode, opcionalmente, definir a opção recursiva para remover também seu conteúdo.

await directoryHandle. removeEntry & # 40; " file. txt " & # 41 ;; aguarde o diretórioHandle. removeEntry & # 40; " Subdiretório ", & # 123; recursive: true & # 125; & # 41 ;;

Permissões

As permissões para a API de acesso ao sistema de arquivos são divididas em componentes de leitura e gravação. Browers geralmente mostra um prompt de permissão separado para leitura e gravação e para cada arquivo ou diretório que você acessar.

Depois de obter permissão, você pode usar o identificador de arquivo ou diretório enquanto o site permanecer aberto. Uma exceção é se o recurso subjacente for alterado ou modificado no disco, caso em que o identificador é invalidado.

Você pode verificar se ainda tem permissão para usar um identificador chamando seu método queryPermission ():

const mode = " read & quot ;; // também pode ser " readwrite " se & # 40; await fileHandle. queryPermission & # 40; & # 123; mode & # 125; & # 41; === " concedido " & # 41; & # 123; // OK & # 125;

Quando você precisar solicitar permissão novamente, use o método requestPermission () da mesma maneira.

Você deve evitar solicitar permissão com muita frequência ou para muitos arquivos. Isso provavelmente criará uma experiência do usuário ruim devido ao aparecimento de vários diálogos sucessivos. Sempre solicite permissão em resposta a uma ação explícita do usuário, como clicar em um botão.

A API não faz provisão para concessões de permissão persistentes. Depois que todas as guias do seu site forem fechadas, todas as permissões de arquivo concedidas serão revogadas.

Conclusão

A API de acesso ao sistema de arquivos é uma das APIs de navegador mais interessantes lançadas nos últimos meses. Ele tem o potencial de transformar os recursos dos aplicativos da web, tornando-os uma alternativa ainda mais viável aos programas de desktop.

Quer você esteja criando um editor de texto, galeria de fotos ou aplicativo empresarial de linha de negócios, a capacidade de interagir com o sistema de arquivos do dispositivo oferece novas possibilidades. Embora o suporte do navegador seja limitado ao Chrome e ao Opera no futuro próximo (a Mozilla vê a API como “ potencialmente muito perigosa ”), o File System Access ajuda a evoluir a web como uma plataforma de aplicativo e reduz ainda mais a lacuna entre os aplicativos da web e nativos.