JavaScript Storage API

Introdução à Storage API

No desenvolvimento web moderno, gerir dados com eficiência é fundamental. A Web Storage API do JavaScript fornece uma forma simples e síncrona de armazenar pares chave/valor diretamente no browser — sem necessidade de ir ao servidor. É a ferramenta mais comum para lembrar preferências do utilizador, armazenar pequenas quantidades de dados em cache e manter o estado da interface entre recarregamentos de página.

Este guia aborda os dois objetos de armazenamento que a API expõe — localStorage e sessionStorage — juntamente com o conjunto completo de métodos, como armazenar objetos, como reagir a alterações entre abas e os erros mais comuns. Ambos os objetos partilham a mesma interface (a interface Storage); a única diferença é durante quanto tempo os dados persistem e com que amplitude são partilhados.

Como a Web Storage nunca é enviada ao servidor, não é adequada para tokens de autenticação de que o backend precisa — para isso existem os cookies.

A Interface Storage

Todos os valores na Web Storage são strings. Tanto localStorage como sessionStorage expõem os mesmos cinco métodos e uma propriedade length:

Os exemplos abaixo usam localStorage, mas todos os métodos funcionam de forma idêntica em sessionStorage.

Compreender o localStorage

O localStorage armazena dados sem data de expiração. Os dados persistem mesmo após o browser ser fechado e reaberto, tornando-o ideal para dados de longa duração, como preferências do utilizador, uma escolha de tema ou um rascunho de formulário.

Armazenar Dados no localStorage

Para armazenar dados, use o método setItem com uma chave e um valor:

// Storing data in localStorage
localStorage.setItem('username', 'JohnDoe');

Ambos os argumentos são convertidos em strings. Escrever setItem('count', 5) armazena efetivamente a string "5", portanto lembre-se de converter de volta ao ler.

Recuperar Dados do localStorage

Use getItem para ler um valor. Se a chave não existir, obtém null (não undefined):

// Retrieving data from localStorage
const username = localStorage.getItem('username');
console.log(username);                 // "JohnDoe"
console.log(localStorage.getItem('missing')); // null

Remover Dados do localStorage

Elimine uma única chave com removeItem, ou apague tudo para a origem com clear:

// Remove one key
localStorage.removeItem('username');

// Remove every key for this origin
localStorage.clear();

clear() afeta apenas a origem atual (esquema + host + porta); nunca toca nos dados de outro site.

Armazenar Objetos: JSON.stringify e JSON.parse

Como os valores de armazenamento devem ser strings, não é possível armazenar um object diretamente — setItem('user', {name: 'Ann'}) armazenaria a string inútil "[object Object]". Serialize com JSON.stringify ao guardar e JSON.parse ao recuperar:

const user = { name: 'Ann', theme: 'dark', visits: 3 };

// Save: serialize the object to a JSON string
localStorage.setItem('user', JSON.stringify(user));

// Load: parse the string back into an object
const restored = JSON.parse(localStorage.getItem('user'));
console.log(restored.theme); // "dark"
console.log(restored.visits + 1); // 4

Consulte Trabalhar com JSON para mais informações sobre serialização, e Objetos JavaScript para os conceitos básicos de objetos.

Iterar sobre as Chaves Armazenadas

Use length em conjunto com key(index) para percorrer tudo o que está armazenado para a origem:

localStorage.setItem('a', '1');
localStorage.setItem('b', '2');

for (let i = 0; i < localStorage.length; i++) {
  const name = localStorage.key(i);
  console.log(`${name} = ${localStorage.getItem(name)}`);
}
// a = 1
// b = 2

Usar o sessionStorage

O sessionStorage partilha a mesma API mas tem uma duração mais curta, por aba. Os dados são apagados quando a sessão da página termina — ou seja, quando a aba é fechada. Abrir o mesmo site numa segunda aba cria um sessionStorage separado, pelo que as duas abas nunca acedem aos dados uma da outra. Isto torna-o perfeito para dados que não devem vazar entre abas, como o progresso de um assistente com múltiplas etapas.

// Store, read, and remove — same methods as localStorage
sessionStorage.setItem('sessionName', 'Session1');
console.log(sessionStorage.getItem('sessionName')); // "Session1"
sessionStorage.removeItem('sessionName');

Reagir a Alterações Entre Abas

Quando o localStorage muda numa aba, o browser dispara um evento storage em todas as outras abas da mesma origem (mas não na aba que fez a alteração). Isto permite manter várias abas sincronizadas — por exemplo, terminar a sessão do utilizador em todo o lado de uma vez:

window.addEventListener('storage', (event) => {
  // event.key, event.oldValue, event.newValue, event.url
  if (event.key === 'theme') {
    console.log('Theme changed in another tab to', event.newValue);
  }
});

Nota: o evento storage é disparado apenas para localStorage (partilhado entre abas), não para sessionStorage.

Lidar com Erros e Limites

As escritas podem lançar um QuotaExceededError quando o limite de ~5 MB é excedido, e o armazenamento pode estar completamente indisponível em modos de navegação privada ou quando os cookies estão desativados. Envolva as escritas em try...catch e verifique a disponibilidade antes de depender da API:

function safeSet(key, value) {
  try {
    localStorage.setItem(key, value);
    return true;
  } catch (err) {
    // QuotaExceededError, or storage blocked by the browser
    console.warn('Storage write failed:', err.name);
    return false;
  }
}

console.log(safeSet('theme', 'dark')); // true (when storage is available)

Boas Práticas para Usar a Web Storage

• Segurança: Considere sempre as implicações de segurança ao armazenar dados sensíveis no browser. Evite armazenar informações confidenciais como palavras-passe ou dados de identificação pessoal.
• Limites de Armazenamento: Tenha atenção às limitações de armazenamento (geralmente cerca de 5 MB) e trate os casos em que o armazenamento pode estar cheio.
• Compatibilidade entre Browsers: Garanta que o seu código lida com cenários em que um browser pode não suportar as Storage APIs.
• Armazenamento Apenas de Strings: A Web Storage aceita apenas strings. Use JSON.stringify() para guardar objetos e JSON.parse() para os recuperar.
• Sincronização Entre Abas: Use o StorageEvent para escutar alterações feitas noutras abas e manter os dados sincronizados.

Um Exemplo Completo para Consolidar Tudo

Esta demonstração mostra como usar a Web Storage API, incluindo localStorage e sessionStorage. Tem botões para armazenar, recuperar e remover dados do armazenamento:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Storage API Interactive Demo</title>
  </head>
  <body>
    <h2>localStorage and sessionStorage Demo</h2>
    <div style="display: flex; gap: 10px">
      <button onclick="storeInLocal()">Store in localStorage</button>
      <button onclick="retrieveFromLocal()">Retrieve from localStorage</button>
      <button onclick="removeFromLocal()">Remove from localStorage</button>
    </div>

    <div style="margin: 20px 0" id="localStorageResult"></div>

    <div style="display: flex; gap: 10px; margin-top: 10px">
      <button onclick="storeInSession()">Store in sessionStorage</button>
      <button onclick="retrieveFromSession()">
        Retrieve from sessionStorage
      </button>
      <button onclick="removeFromSession()">Remove from sessionStorage</button>
    </div>

    <div style="margin-top: 20px" id="sessionStorageResult"></div>

    <script>
      function storeInLocal() {
        localStorage.setItem("demo", "Hi from LocalStorage!");
        document.getElementById("localStorageResult").textContent =
          "Stored in localStorage: " + localStorage.getItem("demo");
      }

      function retrieveFromLocal() {
        const value = localStorage.getItem("demo") || "Nothing in localStorage";
        document.getElementById("localStorageResult").textContent =
          "Retrieved from localStorage: " + value;
      }

      function removeFromLocal() {
        localStorage.removeItem("demo");
        document.getElementById("localStorageResult").textContent =
          "Item removed from localStorage.";
      }

      function storeInSession() {
        sessionStorage.setItem("demo", "Hi from SessionStorage!");
        document.getElementById("sessionStorageResult").textContent =
          "Stored in sessionStorage: " + sessionStorage.getItem("demo");
      }

      function retrieveFromSession() {
        const value =
          sessionStorage.getItem("demo") || "Nothing in sessionStorage";
        document.getElementById("sessionStorageResult").textContent =
          "Retrieved from sessionStorage: " + value;
      }

      function removeFromSession() {
        sessionStorage.removeItem("demo");
        document.getElementById("sessionStorageResult").textContent =
          "Item removed from sessionStorage.";
      }
    </script>
  </body>
</html>

• LocalStorage: Os dados aqui armazenados permanecem mesmo após o browser ser fechado e reaberto, tornando-o perfeito para guardar preferências do utilizador ou outros dados de longo prazo.
• SessionStorage: É semelhante ao localStorage, mas os dados são apagados quando a sessão termina (como quando o browser é fechado).

Ao clicar nos vários botões, pode ver como os dados são adicionados, recuperados e removidos de cada tipo de armazenamento. Os resultados são apresentados diretamente abaixo de cada botão, fornecendo feedback imediato sobre o que está a acontecer com os dados no armazenamento. Esta configuração interativa ajuda a visualizar e compreender como as aplicações web podem lembrar dados entre recarregamentos de página ou sessões do browser.

Além de interagir com as operações de armazenamento através dos botões nesta demonstração, também pode visualizar e gerir os dados armazenados diretamente no seu browser. Abra as ferramentas de desenvolvimento do browser, navegue até à secção Application e procure o separador Storage. Aqui pode ver as entradas de localStorage e sessionStorage.

Esta ferramenta visual permite ver os efeitos das suas ações (como armazenar e remover dados) em tempo real e oferece uma forma prática de explorar como o armazenamento web funciona nos browsers.

Conclusão

A JavaScript Storage API fornece um método robusto e fácil de usar para gerir dados dentro do browser. Ao compreender e aproveitar o localStorage e o sessionStorage, os programadores podem melhorar significativamente a experiência do utilizador nas suas aplicações web. Considere sempre a segurança e os limites de armazenamento para garantir que as suas aplicações são robustas e fáceis de usar. Com estas ferramentas, pode criar estados persistentes e funcionalidades de gestão de dados essenciais para as aplicações web modernas.

Prática