CKTIS / JavaScript
IndexedDB: criar armazenamentos de objetos e abrir transações
Usa `createObjectStore()` para alterar o esquema durante uma atualização e `transaction()` para ler ou escrever registos em armazenamentos existentes.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
db.createObjectStore(name) → IDBObjectStore
db.createObjectStore(name, options) → IDBObjectStore
db.transaction(storeNames) → IDBTransaction
db.transaction(storeNames, mode) → IDBTransaction
db.transaction(storeNames, mode, options) → IDBTransactionIDBDatabase representa uma ligação aberta a uma base de dados IndexedDB. db.createObjectStore(name, options) devolve imediatamente um novo IDBObjectStore, mas só funciona numa transação versionchange ativa. O IndexedDB inicia essa transação quando indexedDB.open() cria a base de dados ou a abre com uma versão superior. Altera o esquema em upgradeneeded. Uma ligação aberta noutro separador pode bloquear a atualização: o pedido de abertura dispara blocked e a ligação anterior pode chamar close() em resposta a versionchange.
O keyPath opcional indica onde extrair a chave do valor, por exemplo, em id. Um array de caminhos define uma chave composta; sem caminho, a chave é guardada separadamente. Por omissão, autoIncrement é false; true ativa um gerador de chaves, mas não se pode combinar com uma cadeia vazia ou um array como keyPath (InvalidAccessError). Um nome de armazenamento duplicado dá ConstraintError, um caminho inválido dá SyntaxError e uma chamada sem transação de atualização dá InvalidStateError.
db.transaction(storeNames, mode, options) devolve imediatamente uma IDBTransaction cujo âmbito é definido por um único nome de armazenamento passado como cadeia de caracteres ou por um iterável não vazio de nomes de armazenamentos existentes, como um array ou um Set. Acede a um deles com tx.objectStore(name). Por omissão, "readonly" só permite leituras; "readwrite" também permite escritas. Não podes escolher "versionchange" aqui (TypeError). Um armazenamento desconhecido dá NotFoundError, uma lista vazia dá InvalidAccessError e uma ligação fechada ou em fecho dá InvalidStateError. A opção options.durability ("default", "strict", "relaxed") indica a preferência de durabilidade ao confirmar a transação; verifica o suporte nos navegadores de destino.
Coloca pedidos em fila apenas enquanto a transação está ativa: na tarefa que a criou ou num manipulador success ou error de um dos seus pedidos. Depois de await fetch(...), a transação pode já ter sido confirmada automaticamente e um pedido posterior pode lançar TransactionInactiveError. O êxito de um pedido não implica o da transação. complete confirma a conclusão com êxito; abort indica que as alterações foram revertidas.
IndexedDB é uma API Web, não faz parte de ECMAScript 2024. O acesso está limitado à mesma origem; as definições do navegador podem restringir o acesso ao armazenamento ou o tempo de conservação dos dados.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB example</title>
</head>
<body>
<script>
(async () => {
const idb = window.indexedDB;
const name = `cktis-notes-${crypto.randomUUID()}`;
const requestResult = (request) => new Promise((resolve, reject) => {
request.onsuccess = () => resolve(request.result);
request.onerror = () => reject(request.error);
});
const finished = (tx) => new Promise((resolve, reject) => {
tx.oncomplete = () => resolve();
tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
});
const open = idb.open(name, 1);
open.onupgradeneeded = () => {
open.result.createObjectStore("notes", { keyPath: "id" });
};
const db = await requestResult(open);
db.onversionchange = () => db.close();
let title;
try {
const write = db.transaction("notes", "readwrite");
write.objectStore("notes").put({ id: 1, title: "IndexedDB" });
await finished(write);
const read = db.transaction("notes");
const get = read.objectStore("notes").get(1);
await finished(read);
title = get.result.title;
} finally {
db.close();
await requestResult(idb.deleteDatabase(name));
}
console.log(title);
})().catch((error) => console.error(error));
</script>
</body>
</html>Resultado
IndexedDB
Disponibiliza o ficheiro HTML por HTTPS e abre-o num navegador onde o armazenamento seja permitido. O exemplo cria uma base de dados com um nome aleatório, lê o registo depois de a escrita ser confirmada, fecha e elimina a base de dados e, por fim, apresenta `IndexedDB` na consola do navegador.
Lições relacionadas
- JavaScript · Lição 31 · Avançado · Versão: 4
Fontes
- IDBDatabase: createObjectStore() method
- IDBDatabase: transaction() method
- IDBFactory: open() method
- Using IndexedDB
- IDBTransaction
- IDBTransaction: durability property
- IndexedDB key characteristics and basic terminology
- IDBObjectStore: put() method
- IDBObjectStore: get() method
- IDBFactory: deleteDatabase() method
- Crypto: randomUUID() method
- ECMAScript® 2024 Language Specification — Overview