⚡ Curso de HTML & HTML5 • Web-ZoneWare

HTML5 Web Storage: LocalStorage e Session | Web Academy

Lição 38 de 50

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.

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:

JavaScript 15 linhas
// 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:

JavaScript 19 linhas
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:

HTML5 5 linhas
<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>
CSS3 34 linhas
/* 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;
}
JavaScript 29 linhas
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();
🧪 Quer testar o LocalStorage e a persistência de tema agora?
⚡ Abrir no Playground IDE →

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:

JavaScript 10 linhas
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:

7. Referências Técnicas & Especificações Oficiais


Rolar para cima