W3docs
pt
Entrar

File API

A File API em JavaScript é uma ferramenta poderosa que permite aos desenvolvedores interagir com arquivos no lado do cliente, possibilitando selecionar, ler e manipular arquivos em aplicações web.

File API em JavaScript: Interagindo com Arquivos do Usuário

A File API em JavaScript é uma ferramenta poderosa que permite aos desenvolvedores web interagir com arquivos no lado do cliente, possibilitando que os usuários selecionem, leiam e manipulem arquivos dentro de aplicações web. Essa API tem diversas aplicações, incluindo upload de arquivos, processamento de conteúdo gerado pelo usuário e realização de operações relacionadas a arquivos. Neste artigo, exploraremos o que é a File API, seus benefícios, quando utilizá-la e alguns casos de uso comuns.

O que é a File API?

A File API é uma API JavaScript que fornece acesso a arquivos selecionados pelo usuário por meio de campos de entrada de arquivo (<input type="file">) ou arquivos arrastados para páginas web. Ela expõe uma pequena família de interfaces que trabalham em conjunto:

  • File — representa um único arquivo escolhido pelo usuário. Carrega metadados como name, size (em bytes), type (tipo MIME) e lastModified (um timestamp). Um File é um tipo especial de Blob.
  • Blob — um bloco de dados binários imutáveis ("Binary Large Object"). Todo File é um Blob, mas você também pode criar seus próprios blobs para download ou upload. Veja o capítulo dedicado ao JavaScript Blob para mais detalhes.
  • FileList — a coleção semelhante a um array retornada por input.files. Acesse seus elementos com [0] ou itere sobre ela.
  • FileReader — um leitor assíncrono que carrega o conteúdo de um arquivo na memória como texto, uma data URL ou um ArrayBuffer.

Como tudo isso é executado no navegador, você pode inspecionar, validar e visualizar arquivos antes de qualquer coisa chegar a um servidor.

A File API apenas lê arquivos que o usuário explicitamente fornece. Uma página nunca pode abrir silenciosamente arquivos arbitrários do disco do visitante — isso é um limite de segurança intencional.

Métodos de leitura em resumo

O FileReader expõe quatro métodos de leitura. Escolha o que corresponde ao resultado desejado:

MétodoTipo de resultadoUso típico
readAsText(file)string.txt, .csv, .json, código-fonte
readAsDataURL(file)string de URL data:pré-visualizações de imagem/áudio/vídeo via src
readAsArrayBuffer(file)ArrayBufferparsing binário, hashing, inspeção de bytes
readAsBinaryString(file)string de byteslegado; prefira readAsArrayBuffer

Navegadores modernos também expõem atalhos baseados em promessas diretamente no blob: await file.text(), await file.arrayBuffer() e file.stream(). Esses frequentemente substituem o FileReader em código novo e combinam naturalmente com async/await.

Quando Usar a File API

A File API é especialmente útil quando você deseja:

  1. Gerenciar uploads de arquivos — permitir que os usuários selecionem e enviem arquivos de seus dispositivos.
  2. Visualizar arquivos — exibir uma miniatura de uma imagem escolhida ou mostrar o texto de um documento antes do upload.
  3. Validar no cliente — rejeitar o tipo MIME errado ou um arquivo muito grande antes de gastar largura de banda com um upload.
  4. Manipular arquivos localmente — recortar imagens, editar texto ou analisar CSV sem uma ida ao servidor.

Para PDFs, vale uma ressalva: a File API não gera PDFs. Ela apenas seleciona, lê e salva arquivos. Para criar um PDF, você precisa de uma biblioteca como o jsPDF, e a File API (via Blob) pode então acionar o download.

Exemplo Básico: Lendo Conteúdo de Arquivo

Aqui está um exemplo simples usando a File API em JavaScript para ler um arquivo de texto selecionado pelo usuário e exibir seu conteúdo. Esta demonstração ajudará você a entender como interagir com arquivos em seus dispositivos usando tecnologias web.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>File Reader Example</title>
  </head>
  <body>
    <h1>Read Text File</h1>
    <p>First, choose a text file, then click the 'Read File' button to see your file's contents.</p>
    <input type="file" id="fileInput" accept=".txt" />
    <button onclick="readFile()">Read File</button>
    <pre id="fileContents"></pre>

    <script>
      function readFile() {
        const fileInput = document.getElementById("fileInput");
        const file = fileInput.files[0]; // Get the first file selected by the user

        if (file) {
          const reader = new FileReader();

          reader.onload = function (e) {
            const contents = e.target.result;
            document.getElementById("fileContents").textContent = contents;
          };

          reader.onerror = function (e) {
            console.error("Error reading file:", e.target.error.message);
          };

          reader.readAsText(file); // Read the file as text
        } else {
          alert("Please select a file.");
        }
      }
    </script>
  </body>
</html>
Experimente Você Mesmo »

Neste código:

  • Seleção de Arquivo: O usuário seleciona um arquivo de texto (um arquivo com extensão .txt) usando o elemento de entrada de arquivo.
  • Leitura do Arquivo: Quando o usuário clica no botão "Read File", o arquivo selecionado é lido como texto. Note que as operações do FileReader são assíncronas; o callback onload é executado somente após o arquivo ter sido completamente lido.
  • Exibição do Arquivo: O conteúdo do arquivo é exibido em um elemento <pre>, preservando a formatação do arquivo de texto.

Este exemplo fornece uma demonstração direta da capacidade da File API de ler e interagir com arquivos selecionados pelo usuário em uma aplicação web.

Inspecionando Metadados de Arquivo

Muitas vezes você precisa dos detalhes de um arquivo antes de fazer qualquer outra coisa — para validá-lo ou para mostrar ao usuário o que ele escolheu. Todo objeto File expõe esses metadados de forma síncrona, sem necessidade de leitura:

const file = fileInput.files[0];

console.log(file.name);          // e.g. "report.pdf"
console.log(file.type);          // MIME type, e.g. "application/pdf"
console.log(file.size);          // size in bytes, e.g. 12048
console.log(file.lastModified);  // ms since the Unix epoch

Uma tarefa comum é converter a contagem de bytes em algo legível por humanos:

function formatBytes(bytes) {
  if (bytes === 0) return "0 B";
  const units = ["B", "KB", "MB", "GB"];
  const i = Math.floor(Math.log(bytes) / Math.log(1024));
  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
}

console.log(formatBytes(0));        // "0 B"
console.log(formatBytes(900));      // "900.0 B"
console.log(formatBytes(2048));     // "2.0 KB"
console.log(formatBytes(5242880));  // "5.0 MB"

Validando Arquivos Antes do Upload

A validação no lado do cliente fornece feedback imediato ao usuário e evita uploads desnecessários. Sempre revalide no servidor também — as verificações no cliente são uma conveniência, não uma garantia de segurança, pois qualquer pessoa pode contorná-las.

function validateImage(file) {
  const allowedTypes = ["image/png", "image/jpeg", "image/webp"];
  const maxSize = 2 * 1024 * 1024; // 2 MB

  if (!allowedTypes.includes(file.type)) {
    return "Only PNG, JPEG, or WebP images are allowed.";
  }
  if (file.size > maxSize) {
    return "File is too large (max 2 MB).";
  }
  return null; // null means "valid"
}

// Simulate two checks:
console.log(validateImage({ type: "image/gif", size: 1000 }));
// "Only PNG, JPEG, or WebP images are allowed."
console.log(validateImage({ type: "image/png", size: 500 }));
// null

Pré-visualizando uma Imagem Antes do Upload

Para exibir uma miniatura de uma imagem escolhida, leia-a como uma data URL e atribua essa string ao src de um elemento <img>. O navegador decodifica o payload base64 diretamente — sem envolvimento do servidor.

<input type="file" id="imageInput" accept="image/*" />
<img id="preview" alt="Preview" width="200" />

<script>
  const input = document.getElementById("imageInput");
  const preview = document.getElementById("preview");

  input.addEventListener("change", () => {
    const file = input.files[0];
    if (!file) return;

    const reader = new FileReader();
    reader.onload = (e) => {
      preview.src = e.target.result; // a "data:image/...;base64,..." URL
    };
    reader.readAsDataURL(file);
  });
</script>

Para arquivos de mídia grandes, prefira URL.createObjectURL(file) em vez de uma data URL — ele retorna uma referência curta blob: sem copiar o arquivo inteiro para uma string. Lembre-se de chamar URL.revokeObjectURL() quando a pré-visualização não for mais necessária para que o navegador possa liberar a memória.

Lendo um Arquivo com Promises Modernas

Nos navegadores atuais, você pode ignorar completamente o FileReader e usar await nos próprios métodos do blob. Isso é mais limpo quando você já está dentro de uma função async:

async function readTextFile(file) {
  const text = await file.text();
  return text.trim().split("\n").length; // count of lines
}

// Simulate a File with the same API as the real Blob:
const fakeFile = new Blob(["line 1\nline 2\nline 3"]);
readTextFile(fakeFile).then((lines) => console.log(lines)); // 3

Enviando um Arquivo para um Servidor

Assim que um arquivo é selecionado, você pode enviá-lo com fetch e um corpo FormData. O navegador define os cabeçalhos corretos de multipart/form-data automaticamente — não defina Content-Type você mesmo:

async function uploadFile(file) {
  const formData = new FormData();
  formData.append("upload", file, file.name);

  const response = await fetch("/api/upload", {
    method: "POST",
    body: formData,
  });
  return response.ok;
}

Veja o capítulo Fetch API para o modelo completo de requisição/resposta.

Armadilhas Comuns

  • FileReader é assíncrono. O resultado só está disponível dentro de onload; ler reader.result na linha seguinte retorna null.
  • input.files pode conter múltiplos arquivos. Adicione o atributo multiple ao input e itere o FileList; caso contrário, você só verá files[0].
  • O value é limpo ao cancelar em alguns navegadores. Reselecionar o mesmo arquivo pode não disparar change; redefina input.value = "" primeiro se precisar detectar isso.
  • file.type pode estar vazio. Para extensões desconhecidas, o tipo MIME pode ser ""; nunca confie nele como única verificação.
  • Object URLs vazam memória. Cada URL.createObjectURL() deve ser correspondido com um URL.revokeObjectURL().

Conclusão

A File API em JavaScript capacita os desenvolvedores web a trabalhar com arquivos do usuário diretamente dentro de aplicações web, abrindo possibilidades para aprimorar as interações do usuário e proporcionar uma experiência de usuário fluida. Seja construindo um uploader de arquivos, um editor de documentos ou qualquer aplicação que exija manipulação de arquivos, a File API equipa você com as ferramentas para criar soluções ricas em funcionalidades de gerenciamento de arquivos no lado do cliente.

Para ir além, explore o capítulo JavaScript Blob para construir e baixar seus próprios dados binários, Drag and Drop com JavaScript para permitir que os usuários soltem arquivos na página, e a Fetch API para enviar arquivos a um servidor.

Prática

Prática
O que você pode fazer com a File API em JavaScript?
O que você pode fazer com a File API em JavaScript?
Was this page helpful?