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 nameStorage.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