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

CKTIS / JavaScript

Storage.length e Storage.key(): contar entradas e ler nomes de chaves

`length` conta as entradas guardadas e `key(index)` devolve o nome de uma chave pela sua posição. A ordem dessas posições não é garantida.

Versão: Current web platform; runtime support varies

Sintaxe

// Web Storage is defined by the HTML Living Standard, not ECMAScript 2024.
storage.length                 // number (read-only)
storage.key(index)             // string | null; zero-based index
storage.getItem(name)          // string | null; lookup by key name

Storage.length/key refere-se a dois membros de uma instância de Storage. A propriedade só de leitura storage.length conta os pares chave–valor guardados nesse momento; não indica o tamanho em bytes nem a quota. O método storage.key(index) devolve o nome da chave como cadeia de caracteres, não o seu valor. As posições começam em zero: passa um inteiro não negativo no intervalo de unsigned long (de 0 a 2 ** 32 - 1). Se o índice convertido for maior ou igual ao length atual, o método devolve null.

Para ler o valor, passa o nome a storage.getItem(name). Este método também pode devolver null, mas, nesse caso, significa que a chave não existe. Verifica o resultado de key() com name !== null, porque a cadeia vazia pode ser um nome de chave válido.

A ordem das chaves depende da implementação e pode mudar após uma alteração. Não assumas que é a ordem de inserção nem guardes um índice como identificador da chave. Se a ordem de apresentação for importante, recolhe os nomes e ordena-os explicitamente. Guardar length não cria uma cópia instantânea: uma alteração durante a iteração pode fazer com que algumas chaves sejam ignoradas ou lidas duas vezes.

Web Storage é definido pela norma HTML e não faz parte do ECMAScript 2024. window.localStorage está associado a uma origem e pode persistir após o reinício do navegador. window.sessionStorage também é separado por separador ou janela de nível superior: mantém-se após recarregar a página, mas está associado à sessão da página. Não pressuponhas que está disponível em todos os ambientes de execução. Obter qualquer um dos objetos pode lançar SecurityError devido a uma origem opaca ou a uma política do navegador. Uma escrita pode lançar QuotaExceededError, por exemplo quando a quota se esgota.

Exemplos

(() => {
  function demonstrate(storage) {
    if (storage.length !== 0) {
      throw new Error("Use an empty sessionStorage area.");
    }

    try {
      console.log(storage.length);
      storage.setItem("theme", "dark");
      storage.setItem("lang", "en");

      const count = storage.length;
      const names = [];
      for (let index = 0; index < count; index++) {
        const name = storage.key(index);
        if (name !== null) names.push(name);
      }

      console.log(count);
      console.log(JSON.stringify(names.sort().map(name => [name, storage.getItem(name)])));
      console.log(storage.key(count));
    } finally {
      storage.removeItem("theme");
      storage.removeItem("lang");
    }
  }

  const storage = globalThis.sessionStorage;
  if (storage !== undefined) {
    demonstrate(storage);
  } else {
    // If Node.js 24 has not exposed Web Storage, enable it in a fresh process.
    const { execFileSync } = require("node:child_process");
    execFileSync(
      process.execPath,
      ["--experimental-webstorage", "-e", `(${demonstrate.toString()})(globalThis.sessionStorage);`],
      { stdio: "inherit" },
    );
  }
})();

Resultado

0
2
[["lang","en"],["theme","dark"]]
null

Executa o código na consola do navegador numa página HTTP(S), num separador de teste com `sessionStorage` vazio e acessível, sem outro código a alterar essa área. A ordenação torna o resultado independente da ordem das chaves no navegador. `key(count)` devolve `null` e `finally` remove apenas as duas entradas usadas no exemplo. Para Node.js 24, guarda o código como `main.js` e executa `node main.js`; se necessário, o exemplo ativa a API Web Storage integrada num processo filho.

Lições relacionadas

  • JavaScript · Lição 42 · Avançado · Versão: 4

Fontes