Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Storage.setItem — guardar e substituir um valor

Storage.setItem guarda texto associado a uma chave em localStorage ou sessionStorage, substituindo o valor anterior. A escrita pode falhar, pelo que deve ter em conta as exceções e as restrições de acesso ao armazenamento.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

storage.setItem(key, value)

Chame Storage.setItem num objeto localStorage ou sessionStorage: storage.setItem(key, value). O método cria uma entrada ou substitui o valor de uma chave existente e devolve undefined. Esta API faz parte da norma HTML, não de uma edição específica de ECMAScript. Os motores de browser modernos suportam-na; a presença do Node 24 num repositório não comprova a disponibilidade de uma API de browser.

As chaves e os valores são convertidos em cadeias de caracteres. Para guardar um objeto, serialize-o explicitamente numa cadeia de caracteres. Ao ler o valor guardado, o armazenamento devolve uma cadeia de caracteres que a aplicação tem de descodificar de acordo com o formato usado na escrita. Se escrever dados em JSON com JSON.stringify, use JSON.parse para descodificar essa cadeia. localStorage guarda dados de uma origem entre sessões, enquanto sessionStorage também é separado por contexto de navegação de nível superior, normalmente um separador. Os dados podem ser eliminados.

Uma escrita falhada pode lançar QuotaExceededError; o próprio acesso ao armazenamento pode lançar SecurityError. Envolva o acesso e a escrita em try/catch se a aplicação tiver de funcionar sem armazenamento. Escrever texto idêntico não altera nada. A notificação storage destina-se a outros documentos elegíveis, não à janela que efetua a escrita.

Exemplos

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Storage.setItem: writing and replacing text</title>
</head>
<body>
<h1>Replacing a storage value</h1>
<p id="source"></p>
<script>
  function writeValues(storage) {
    let key = 'cktis:setItem';
    while (storage.getItem(key) !== null) key += ':';

    try {
      storage.setItem(key, 'first');
      const before = storage.getItem(key);
      storage.setItem(key, 'second');
      return [before, storage.getItem(key)];
    } finally {
      storage.removeItem(key);
    }
  }

  let lines;
  let source = 'Using browser sessionStorage.';
  try {
    lines = writeValues(window.sessionStorage);
  } catch (error) {
    if (error.name !== 'SecurityError' && error.name !== 'QuotaExceededError') throw error;
    source = 'Browser storage is unavailable. Using an in-memory fixture, not Web Storage.';
    const entries = new Map();
    lines = writeValues({
      getItem(key) { return entries.has(key) ? entries.get(key) : null; },
      setItem(key, value) { entries.set(key, String(value)); },
      removeItem(key) { entries.delete(key); }
    });
  }
  document.getElementById('source').textContent = source;
  for (const line of lines) console.log(line);
</script>
</body>
</html>

Resultado

first
second

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes