HTML5 Web Storage: LocalStorage e Session | Web Academy
Antes da chegada do HTML5, a única maneira de persistir pequenas informações ou preferências do usuário no navegador era através dos tradicionais Cookies HTTP. No entanto, os cookies possuem um limite rígido de apenas 4 KB e, pior ainda, são enviados compulsoriamente nos cabeçalhos de rede a cada nova requisição (até mesmo ao carregar imagens e estilos). A HTML5 Web Storage API revolucionou esse cenário ao fornecer um mecanismo nativo de armazenamento chave-valor local de até 5 a 10 MB por domínio, mantendo os dados estritamente no cliente sem degradar o tráfego de rede.
📑 Índice do Conteúdo
1. A Diferença Fundamental: LocalStorage vs SessionStorage
A especificação do Web Storage divide o armazenamento em dois mecanismos complementares que compartilham exatamente os mesmos métodos, diferindo apenas pelo seu ciclo de vida:
| Característica | LocalStorage | SessionStorage |
|---|---|---|
| Tempo de Vida | Permanente. Sobrevive ao fechamento da aba, do navegador e à reinicialização do sistema operacional. | Temporário. Os dados são apagados automaticamente quando a aba específica é fechada. |
| Sobrevive ao Reload (F5)? | Sim, permanece intacto. | Sim, permanece intacto durante a mesma sessão. |
| Compartilhamento entre Abas | Compartilhado entre todas as abas e janelas da mesma origem (mesmo domínio/porta). | Isolado exclusivamente na aba onde foi criado (não vaza para outras abas). |
| Capacidade Típica | Em torno de 5 MB por origem. | Em torno de 5 MB por origem. |
| Cenário Ideal | Tema escuro/claro, preferências de layout e rascunhos persistentes. | Etapas de checkout, filtros de busca temporários e dados de um assistente de formulário. |
2. Métodos Essenciais da API de Armazenamento
Tanto o window.localStorage quanto o window.sessionStorage implementam a interface Storage:
// 1. Gravar um item (Chave, Valor)
localStorage.setItem('preferenciaTema', 'dark');
// 2. Recuperar um item (Retorna string ou null se não existir)
const temaAtual = localStorage.getItem('preferenciaTema');
console.log(temaAtual); // ___WZW_STR_0___
// 3. Remover uma chave específica
localStorage.removeItem('preferenciaTema');
// 4. Limpar todos os registros do domínio de uma vez
localStorage.clear();
// 5. Saber quantos itens estão armazenados
console.log(localStorage.length);
3. Salvando Objetos e Arrays com JSON
O Web Storage só aceita valores no formato de strings de texto puro. Se você tentar passar um objeto diretamente para o setItem(), o JavaScript converterá o dado para a inútil string "[object Object]".
Para contornar essa característica, usamos a serialização com JSON.stringify() ao salvar e a restauração com JSON.parse() ao ler:
const configuracoesUsuario = {
nome: 'Carlos Eduardo',
notificacoes: true,
idioma: 'pt-BR',
itensPorPagina: 25
};
// ❌ FORMA ERRADA:
// localStorage.setItem('config', configuracoesUsuario); // grava "[object Object]"
// ✅ FORMA CORRETA (Serializando para texto JSON):
localStorage.setItem('config', JSON.stringify(configuracoesUsuario));
// Recuperando e convertendo de volta para objeto real:
const salvo = localStorage.getItem('config');
if (salvo) {
const objetoRestaurado = JSON.parse(salvo);
console.log(objetoRestaurado.nome); // ___WZW_STR_0___
}
4. Código Prático Completo: Seletor de Tema Persistente (Dark Mode)
No exemplo abaixo, implementamos a troca de tema visual da página. A escolha do usuário é gravada no localStorage e restabelecida automaticamente sempre que ele retornar ao site:
<div class="wzw-theme-box">
<h3>🎨 Personalização de Tema da Página</h3>
<p>Alterne o modo de exibição. Sua escolha continuará ativa mesmo se fechar o navegador:</p>
<button id="btnAlternarTema" class="btn-theme">🌙 Ativar Modo Escuro</button>
</div>
/* Cores padrão (Modo Claro) */
body {
background-color: #ffffff;
color: #1e293b;
transition: background-color 0.3s, color 0.3s;
}
/* Cores quando a classe dark-theme estiver no body */
body.dark-theme {
background-color: #0f172a;
color: #f8fafc;
}
.wzw-theme-box {
padding: 20px;
border: 1px solid #cbd5e1;
border-radius: 8px;
max-width: 480px;
}
body.dark-theme .wzw-theme-box {
border-color: #334155;
background-color: #1e293b;
}
.btn-theme {
padding: 10px 18px;
background-color: #3b82f6;
color: #fff;
border: none;
border-radius: 6px;
cursor: pointer;
font-weight: 600;
}
const botaoTema = document.getElementById('btnAlternarTema');
// 1. Ao carregar a página, verifica se já existe tema salvo
function aplicarTemaInicial() {
const temaSalvo = localStorage.getItem('wzw_tema');
if (temaSalvo === 'dark') {
document.body.classList.add('dark-theme');
botaoTema.textContent = '☀️ Ativar Modo Claro';
} else {
document.body.classList.remove('dark-theme');
botaoTema.textContent = '🌙 Ativar Modo Escuro';
}
}
// 2. Alterna o tema e grava a nova preferência
botaoTema.addEventListener('click', () => {
const modoEscuroAtivo = document.body.classList.toggle('dark-theme');
if (modoEscuroAtivo) {
localStorage.setItem('wzw_tema', 'dark');
botaoTema.textContent = '☀️ Ativar Modo Claro';
} else {
localStorage.setItem('wzw_tema', 'light');
botaoTema.textContent = '🌙 Ativar Modo Escuro';
}
});
// Executa na inicialização
aplicarTemaInicial();
5. Sincronização entre Abas com o Evento Storage
Uma funcionalidade surpreendente do localStorage é que, sempre que outra aba do mesmo domínio altera um item, o navegador dispara o evento storage em todas as outras abas abertas simultaneamente:
window.addEventListener('storage', (event) => {
console.log(`Chave alterada em outra aba: ${event.key}`);
console.log(`Valor anterior: ${event.oldValue}`);
console.log(`Novo valor: ${event.newValue}`);
// Se o usuário mudou o tema na aba 2, atualiza a aba 1 automaticamente!
if (event.key === 'wzw_tema') {
aplicarTemaInicial();
}
});
⚠️ Alerta de Segurança Crítico: XSS e Tokens Sensíveis
O Web Storage é acessível por qualquer script JavaScript executado na página. Isso significa que, se sua aplicação sofrer um ataque de injeção de código malicioso (XSS – Cross-Site Scripting), o invasor poderá roubar todo o conteúdo com uma simples chamada localStorage.getItem().
A regra de ouro da indústria: Nunca salve dados financeiros, senhas ou tokens de autenticação críticos (como JWTs com permissões administrativas) no localStorage. Para autenticação segura de sessões, utilize Cookies HTTP com as diretivas HttpOnly, Secure e SameSite=Strict, que impedem o acesso do script ao cookie.
6. Ferramentas Relacionadas & Próximos Passos
Continue expandindo sua arquitetura web com as ferramentas e lições da nossa suíte:
- Central do Desenvolvedor Web: Conversores JSON, geradores de hashes e manipuladores de strings.
- Hub Master de Imagens: Otimize ativos visuais salvos em cache ou convertidos para Base64.
- Lição 37: API de Geolocalização: Combine a captura de coordenadas com salvamento no LocalStorage.
- Lição 39: Web Workers & Multithreading: Processe tarefas pesadas em background sem travar a interface do usuário.
7. Referências Técnicas & Especificações Oficiais
- WHATWG HTML Living Standard: Web Storage Specification
- MDN Web Docs: Web Storage API Guide
- OWASP Foundation: HTML5 Web Storage Security Cheat Sheet