HTML5 Web Storage: LocalStorage e Session | Web Academy

Web-Zoneware — Wed, 21 Oct 2026 03:56:45 +0000

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);

// 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); // "dark"

// 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___
}

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); // "Carlos Eduardo"
}

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

 class="wzw-theme-box">
    🎨 Personalização de Tema da Página
    Alterne o modo de exibição. Sua escolha continuará ativa mesmo se fechar o navegador:
     id="btnAlternarTema" class="btn-theme">🌙 Ativar Modo Escuro

<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;
}

/* 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();

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();
    }
});

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

O post HTML5 Web Storage: LocalStorage e Session | Web Academy apareceu primeiro em Web-Zoneware.

Arquivos storage event html5 - Web-Zoneware