CKTIS / JavaScript
IndexedDB: criar um índice, inserir, contar e ler registos
Cria um índice secundário, insere registos sem os substituir e pesquisa pela chave primária ou pela chave do índice.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
store.createIndex(name, keyPath)
store.createIndex(name, keyPath, options)
store.count()
store.count(query)
store.add(value)
store.add(value, key)
store.getAll()
store.getAll(query)
store.getAll(query, count)
store.getAll(options)
store.index(name)Um IDBObjectStore representa um armazém de objetos associado a uma transação. Cada registo tem uma chave primária e um valor. IndexedDB é uma API da Web, não faz parte do ECMAScript; o acesso segue a política de mesma origem.
createIndex(name, keyPath, options) devolve imediatamente um IDBIndex, mas só pode ser chamado numa transação versionchange ativa, normalmente em upgradeneeded. O caminho da chave indica de onde extrair a chave do índice; não adiciona campos ao registo. unique: true impede chaves de índice duplicadas e multiEntry: true indexa em separado os elementos válidos de um array. Ambas as opções são false por omissão. Não podes combinar multiEntry: true com um caminho composto expresso como array de caminhos.
add(value, key) guarda uma cópia estruturada e coloca a nova chave em request.result. Omite o segundo argumento se a chave estiver no valor; indica-o se a chave for guardada à parte e não houver gerador. Uma chave primária duplicada ou uma violação da unicidade de um índice faz o pedido falhar com ConstraintError. Usa put() para inserir ou substituir pela chave primária.
count(query) dá um número e getAll(query, count) dá um array de cópias dos valores, vazio se não houver correspondências. Ambos aceitam uma chave primária ou um IDBKeyRange e abrangem todo o armazém sem filtro. Um count positivo limita o número de valores de getAll(). A ordem predefinida é crescente pela chave primária. A forma mais recente getAll({ query, count, direction }) permite usar, por exemplo, "prev"; verifica o suporte no navegador de destino.
index(name) devolve imediatamente um IDBIndex existente da mesma transação. Um nome desconhecido lança NotFoundError; distingue-se entre maiúsculas e minúsculas. store.getAll("sci-fi") procura pela chave primária, enquanto store.index("byGenre").getAll("sci-fi") devolve os valores dos registos que correspondem à chave do índice.
add(), count() e getAll() devolvem um IDBRequest, não uma Promise. Lê result após success e trata error. Numa transação normal, escrever exige o modo readwrite. Coloca os pedidos em fila enquanto a transação estiver ativa: a espera por outra operação assíncrona pode deixá-la terminar. O sucesso de um pedido não confirma a transação; para isso, espera pelo evento complete.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>IndexedDB object store methods</title>
<script>
(() => {
const dbName = `cktis-books-${crypto.randomUUID()}`;
const open = indexedDB.open(dbName, 1);
open.onupgradeneeded = () => {
const store = open.result.createObjectStore('books', { keyPath: 'id' });
store.createIndex('byGenre', 'genre');
};
open.onerror = () => console.error(open.error);
open.onsuccess = () => {
const db = open.result;
const tx = db.transaction('books', 'readwrite');
const store = tx.objectStore('books');
const cleanup = () => {
db.close();
const deletion = indexedDB.deleteDatabase(dbName);
deletion.onerror = () => console.error(deletion.error);
};
tx.onabort = () => {
console.error(tx.error);
cleanup();
};
const added = store.add({ id: 3, title: 'Orbit', genre: 'sci-fi' });
store.add({ id: 1, title: 'Dunes', genre: 'sci-fi' });
store.add({ id: 2, title: 'Herbs', genre: 'guide' });
const total = store.count();
const all = store.getAll();
const matches = store.index('byGenre').getAll('sci-fi');
tx.oncomplete = () => {
const titles = (request) => request.result.map((book) => book.title).join(', ');
console.log(`Added key: ${added.result}`);
console.log(`Total: ${total.result}`);
console.log(`All: ${titles(all)}`);
console.log(`Sci-fi: ${titles(matches)}`);
cleanup();
};
};
})();
</script>Resultado
Added key: 3 Total: 3 All: Dunes, Herbs, Orbit Sci-fi: Dunes, Orbit
Disponibiliza este documento HTML por HTTPS, abre-o num navegador e consulta a consola de desenvolvimento. O exemplo cria uma base de dados temporária independente e elimina-a no fim. Insere três livros fora da ordem das chaves primárias e, após a confirmação da transação, mostra todos os títulos por `id` e os selecionados pelo índice de género.
Lições relacionadas
- JavaScript · Lição 21 · Intermédio · Versão: 3
Fontes
- IDBObjectStore: createIndex() method
- IDBObjectStore: count() method
- IDBObjectStore: add() method
- IDBObjectStore: getAll() method
- IDBObjectStore: index() method
- IDBIndex: getAll() method
- IDBTransaction
- IDBTransaction: complete event
- IndexedDB key characteristics and basic terminology
- Using IndexedDB
- Crypto: randomUUID() method