Os navegadores já lidam com arquivos e diretórios há muito tempo. A API File oferece recursos para representar objetos de arquivo em aplicativos da Web, bem como selecioná-los e acessar os dados de maneira programática. No entanto, quando você olha mais de perto, percebe que nem tudo que reluz é ouro.
A maneira tradicional de lidar com arquivos
Como abrir arquivos
Como desenvolvedor, você pode abrir e ler arquivos pelo
elemento
<input type="file">
.
Na forma mais simples, abrir um arquivo pode ser parecido com o exemplo de código abaixo.
O objeto input
fornece uma FileList
,
que, no caso abaixo, consiste em apenas um
File
.
Um File
é um tipo específico de Blob
e pode ser usado em qualquer contexto em que um Blob possa.
const openFile = async () => {
return new Promise((resolve) => {
const input = document.createElement('input');
input.type = 'file';
input.addEventListener('change', () => {
resolve(input.files[0]);
});
input.click();
});
};
Abrir diretórios
Para abrir pastas (ou diretórios), defina o
atributo
<input webkitdirectory>
.
Fora isso, tudo funciona da mesma forma que acima.
Apesar do nome prefixado pelo fornecedor,
webkitdirectory
não pode ser usado apenas nos navegadores Chromium e WebKit, mas também no Edge baseado em EdgeHTML legado, bem como no Firefox.
Salvar (em vez de fazer o download) de arquivos
Para salvar um arquivo, tradicionalmente, você está limitado a fazer o download de um arquivo,
o que funciona graças ao
atributo
<a download>
.
Com um Blob, é possível definir o atributo href
do âncora para um URL blob:
que pode ser acessado pelo
método
URL.createObjectURL()
.
const saveFile = async (blob) => {
const a = document.createElement('a');
a.download = 'my-file.txt';
a.href = URL.createObjectURL(blob);
a.addEventListener('click', (e) => {
setTimeout(() => URL.revokeObjectURL(a.href), 30 * 1000);
});
a.click();
};
O problema
Uma grande desvantagem da abordagem de download é que não há como fazer um fluxo clássico de abrir→editar→salvar, ou seja, não há como substituir o arquivo original. Em vez disso, você terá uma nova cópia do arquivo original na pasta de downloads padrão do sistema operacional sempre que "salvar".
A API File System Access
A API File System Access simplifica muito as operações de abertura e salvamento. Ele também permite salvamento real, ou seja, você pode não apenas escolher onde salvar um arquivo, mas também substituir um arquivo existente.
Como abrir arquivos
Com a API File System Access,
abrir um arquivo é uma questão de uma chamada para o método window.showOpenFilePicker()
.
Essa chamada retorna um identificador de arquivo, em que você pode acessar o File
real pelo método getFile()
.
const openFile = async () => {
try {
// Always returns an array.
const [handle] = await window.showOpenFilePicker();
return handle.getFile();
} catch (err) {
console.error(err.name, err.message);
}
};
Abrir diretórios
Abra um diretório chamando
window.showDirectoryPicker()
, que torna os diretórios selecionáveis na caixa de diálogo de arquivo.
Como salvar arquivos
Salvar arquivos também é simples.
Em um identificador de arquivo, você cria um stream gravável usando createWritable()
,
grava os dados do Blob chamando o método write()
do stream
e, por fim, fecha o stream chamando o método close()
dele.
const saveFile = async (blob) => {
try {
const handle = await window.showSaveFilePicker({
types: [{
accept: {
// Omitted
},
}],
});
const writable = await handle.createWritable();
await writable.write(blob);
await writable.close();
return handle;
} catch (err) {
console.error(err.name, err.message);
}
};
Introdução ao browser-fs-access
Por mais perfeita que a API File System Access seja, ela ainda não está amplamente disponível.
É por isso que vejo a API File System Access como um aprimoramento progressivo. Por isso, quero usar o JavaScript quando o navegador for compatível com ele e usar a abordagem tradicional se não for; sem punir o usuário com downloads desnecessários de código JavaScript sem suporte. A biblioteca browser-fs-access é minha resposta para esse desafio.
Filosofia de design
Como a API File System Access ainda pode mudar no futuro,
a API browser-fs-access não é modelada a partir dela.
Ou seja, a biblioteca não é um polyfill,
mas um ponyfill.
É possível importar (de forma estática ou dinâmica) exclusivamente qualquer funcionalidade necessária para manter o app o menor possível.
Os métodos disponíveis são
fileOpen()
,
directoryOpen()
e
fileSave()
.
Internamente, o recurso da biblioteca detecta se a API File System Access é compatível
e, em seguida, importa o caminho de código correspondente.
Como usar a biblioteca browser-fs-access
Os três métodos são intuitivos de usar.
É possível especificar o mimeTypes
ou o arquivo extensions
aceito pelo app e definir uma flag multiple
para permitir ou não a seleção de vários arquivos ou diretórios.
Para mais detalhes, consulte a documentação da API browser-fs-access.
O exemplo de código abaixo mostra como abrir e salvar arquivos de imagem.
// The imported methods will use the File
// System Access API or a fallback implementation.
import {
fileOpen,
directoryOpen,
fileSave,
} from 'https://unpkg.com/browser-fs-access';
(async () => {
// Open an image file.
const blob = await fileOpen({
mimeTypes: ['image/*'],
});
// Open multiple image files.
const blobs = await fileOpen({
mimeTypes: ['image/*'],
multiple: true,
});
// Open all files in a directory,
// recursively including subdirectories.
const blobsInDirectory = await directoryOpen({
recursive: true
});
// Save a file.
await fileSave(blob, {
fileName: 'Untitled.png',
});
})();
Demonstração
Confira o código acima em ação em uma demonstração do Glitch. O código-fonte dele também está disponível lá. Por motivos de segurança, os subframes de origem cruzada não podem mostrar um seletor de arquivos. Portanto, a demonstração não pode ser incorporada a este artigo.
A biblioteca browser-fs-access no mundo real
No meu tempo livre, contribuo um pouco para uma PWA instalável chamada Excalidraw, uma ferramenta de lousa interativa que permite esboçar diagramas com facilidade com uma sensação de desenho à mão. Ele é totalmente responsivo e funciona bem em vários dispositivos, de smartphones pequenos a computadores com telas grandes. Isso significa que ele precisa lidar com arquivos em todas as plataformas, mesmo que elas ofereçam suporte à API File System Access. Isso o torna um ótimo candidato para a biblioteca browser-fs-access.
Por exemplo, posso iniciar um desenho no meu iPhone, salvá-lo (tecnicamente: fazer o download, já que o Safari não oferece suporte à API File System Access) na pasta "Downloads" do iPhone, abrir o arquivo no computador (depois de transferir do meu smartphone), modificar o arquivo e substituí-lo com minhas alterações ou até mesmo salvar como um novo arquivo.
Exemplo de código real
Confira abaixo um exemplo real de browser-fs-access conforme usado no Excalidraw.
Este trecho foi retirado de
/src/data/json.ts
.
O método saveAsJSON()
é de interesse especial, pois ele transmite um identificador de arquivo ou null
para o método fileSave()
do browser-fs-access, o que faz com que ele seja substituído quando um identificador é fornecido
ou salvo em um novo arquivo, se não for.
export const saveAsJSON = async (
elements: readonly ExcalidrawElement[],
appState: AppState,
fileHandle: any,
) => {
const serialized = serializeAsJSON(elements, appState);
const blob = new Blob([serialized], {
type: "application/json",
});
const name = `${appState.name}.excalidraw`;
(window as any).handle = await fileSave(
blob,
{
fileName: name,
description: "Excalidraw file",
extensions: ["excalidraw"],
},
fileHandle || null,
);
};
export const loadFromJSON = async () => {
const blob = await fileOpen({
description: "Excalidraw files",
extensions: ["json", "excalidraw"],
mimeTypes: ["application/json"],
});
return loadFromBlob(blob);
};
Considerações sobre a interface
Seja no Excalidraw ou no seu app,
a interface precisa se adaptar à situação de suporte do navegador.
Se a API File System Access tiver suporte (if ('showOpenFilePicker' in window) {}
),
você poderá mostrar um botão Save As, além de um botão Save.
As capturas de tela abaixo mostram a diferença entre a barra de ferramentas responsiva do aplicativo principal do Excalidraw no iPhone e no Chrome para computadores.
Observe que, no iPhone, o botão Save As está ausente.
Conclusões
Trabalhar com arquivos de sistema tecnicamente funciona em todos os navegadores mais recentes. Em navegadores com suporte à API File System Access, você pode melhorar a experiência permitindo realizar o salvamento e a substituição reais (não apenas o download) de arquivos e permitindo que os usuários criem novos arquivos onde quiserem, tudo isso enquanto permanecem funcionais em navegadores que não oferecem suporte à API File System Access. O browser-fs-access facilita sua vida ao lidar com as sutilezas do aprimoramento progressivo e tornar seu código o mais simples possível.
Agradecimentos
Este artigo foi revisado por Joe Medley e Kayce Basques. Agradeço aos colaboradores do Excalidraw pelo trabalho no projeto e por analisar minhas solicitações de pull. Imagem principal de Ilya Pavlov no Unsplash.