CKTIS / JavaScript
IndexedDB: criar um índice, inserir um registo e pesquisar pelo índice
Cria um índice secundário numa atualização da base de dados, insere sem substituir e pesquisa pela chave do índice em vez da chave primária.
Versão: Current web platform; runtime support varies
Sintaxe
store.createIndex(name, keyPath)
store.createIndex(name, keyPath, { unique, multiEntry })
store.add(value)
store.add(value, key)
store.index(name)createIndex(), add() e index() são métodos de instância de IDBObjectStore na API Web IndexedDB, não em ECMAScript. IndexedDB segue a política da mesma origem; a disponibilidade depende do ambiente de execução e das definições de armazenamento do navegador.
store.createIndex(name, keyPath, options) devolve imediatamente um IDBIndex, mas a alteração ao esquema só fica definitiva se a transação for confirmada. Chama o método numa transação versionchange ativa, normalmente em upgradeneeded, ao criar a base de dados ou aumentar a sua versão. O nome identifica o índice; o caminho da chave determina a chave do índice a partir do registo sem lhe acrescentar um campo. IndexedDB indexa os registos existentes e mantém o índice atualizado automaticamente.
unique e multiEntry têm false como valor predefinido. unique: true impede chaves de índice iguais em registos diferentes; duplicados existentes podem abortar a atualização. multiEntry: true indexa separadamente os elementos válidos de um array em vez de usar o array inteiro como chave. Não pode ser combinado com um array de caminhos para uma chave composta (InvalidAccessError). Um nome de índice já utilizado provoca imediatamente ConstraintError.
store.add(value[, key]) insere uma cópia estruturada sem substituir um registo existente. Usa uma transação readwrite ou versionchange ativa. Omite key se a chave primária estiver incluída no valor; indica-a se for externa e não houver gerador. Se o pedido IDBRequest tiver êxito, result contém a chave primária, mas só o evento complete da transação confirma a gravação. Uma chave primária ou de índice único duplicada faz falhar o pedido com ConstraintError. put() pode substituir um registo, mas também tem de respeitar a unicidade do índice.
store.index(name) devolve o IDBIndex existente, associado à mesma transação. Não cria um índice nem lê um registo. Um nome inexistente provoca NotFoundError; há distinção entre maiúsculas e minúsculas. Numa transação ativa, index.get(key) pede o primeiro registo correspondente à chave do índice, não à chave primária. Não reutilizes o objeto para fazer leituras depois de a transação terminar.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB: insert and look up a contact</title>
</head>
<body>
<script>
(async () => {
const { indexedDB, crypto } = window;
const name = `cktis-index-${crypto.randomUUID()}`;
const resultOf = (request) => new Promise((resolve, reject) => {
request.onsuccess = () => resolve(request.result);
request.onerror = () => reject(request.error);
});
const committed = (tx) => new Promise((resolve, reject) => {
tx.oncomplete = () => resolve();
tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
});
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => {
const store = open.result.createObjectStore('contacts', { keyPath: 'id' });
store.createIndex('byEmail', 'email', { unique: true });
};
const db = await resultOf(open);
let contact;
try {
const write = db.transaction('contacts', 'readwrite');
write.objectStore('contacts').add({ id: 7, email: 'ada@example.test' });
await committed(write);
const read = db.transaction('contacts', 'readonly');
const lookup = read.objectStore('contacts').index('byEmail').get('ada@example.test');
await committed(read);
contact = lookup.result;
} finally {
db.close();
await resultOf(indexedDB.deleteDatabase(name));
}
console.log(JSON.stringify(contact));
})().catch((error) => console.error(error));
</script>
</body>
</html>Resultado
{"id":7,"email":"ada@example.test"}Disponibiliza o ficheiro HTML num endereço HTTPS de confiança e abre-o num navegador com IndexedDB e `crypto.randomUUID()` disponíveis. O exemplo cria uma base de dados separada, pesquisa por `email` depois de a escrita ser confirmada e fecha e elimina a base de dados antes de apresentar o resultado na consola do navegador.
Lições relacionadas
- JavaScript · Lição 31 · Avançado · Versão: 4