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

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