CKTIS / JavaScript
IndexedDB: ler e deslocar um cursor com `value` e `continue()`
Lê o valor do registo atual através de um cursor IndexedDB e pede o registo seguinte ou avança para uma posição determinada por uma chave.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
cursor.value // Read-only property of IDBCursorWithValue
cursor.continue() // Request the next eligible position; returns undefined
cursor.continue(key) // Request the next eligible position at or beyond key in the cursor's direction; returns undefinedIDBCursor.value/continue designa dois membros da API: a propriedade só de leitura IDBCursorWithValue.value e o método herdado IDBCursor.continue(). Quando um pedido openCursor() devolve um cursor como resultado, cursor.value contém o valor armazenado do registo atual. Alterar campos do objeto obtido não guarda as alterações; para as escrever, usa, por exemplo, cursor.update() numa transação readwrite. Um cursor de openKeyCursor() tem continue(), mas não tem value.
cursor.continue() pede o próximo registo elegível no sentido do cursor e devolve undefined. cursor.continue(key) procura a primeira posição seguinte com chave >= key para next ou nextunique, ou <= key para prev ou prevunique. A chave de destino não precisa de existir e o intervalo inicial continua a aplicar-se. Num repositório de objetos, compara-se a chave primária; num índice, compara-se a chave do índice (cursor.key).
Lê request.result em cada evento success do mesmo pedido. null significa que não houve correspondências ou que a iteração terminou. Lê o valor e chama continue() no máximo uma vez antes de passar o controlo a uma tarefa posterior, como a função de retorno de um temporizador. Uma chave inválida ou que não esteja estritamente mais à frente no sentido escolhido provoca DataError. Repetir a chamada antes do resultado seguinte, não ter uma posição atual ou ter a fonte eliminada pode provocar InvalidStateError. Uma transação inativa provoca TransactionInactiveError.
IndexedDB é uma API da Web, não faz parte de ECMAScript 2024. A disponibilidade depende do ambiente de execução e do contexto. O acesso aos dados respeita a política da mesma origem.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB cursor example</title>
</head>
<body>
<script>
(() => {
const name = `cktis-cursor-${crypto.randomUUID()}`;
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => {
const store = open.result.createObjectStore('items');
store.add({ name: 'Ada' }, 1);
store.add({ name: 'Bo' }, 2);
store.add({ name: 'Lin' }, 4);
};
open.onerror = () => console.error(open.error);
open.onsuccess = () => {
const db = open.result;
const tx = db.transaction('items', 'readonly');
const request = tx.objectStore('items').openCursor();
const cleanup = () => {
db.close();
const deletion = indexedDB.deleteDatabase(name);
deletion.onerror = () => console.error(deletion.error);
};
tx.oncomplete = cleanup;
tx.onabort = () => {
console.error(tx.error);
cleanup();
};
request.onsuccess = () => {
const cursor = request.result;
if (cursor === null) {
console.log('Done');
return;
}
console.log(`${cursor.key}: ${cursor.value.name}`);
if (cursor.key === 1) {
cursor.continue(3);
} else {
cursor.continue();
}
};
};
})();
</script>
</body>
</html>Resultado
1: Ada 4: Lin Done
Abre este documento HTML por HTTPS como página de nível superior num navegador com IndexedDB e `crypto.randomUUID()` disponíveis. Vê o resultado na consola de programador. O exemplo cria uma base de dados de teste separada e pede a sua eliminação no fim. `continue(3)` salta a chave `2` e chega a `4` porque a chave `3` não existe. O `continue()` seguinte dá o resultado `null` e o gestor do evento imprime `Done`.
Lições relacionadas
- JavaScript · Lição 21 · Intermédio · Versão: 3
Fontes
- IDBCursorWithValue: value property
- IDBCursor: continue() method
- IDBObjectStore: openCursor() method
- IDBIndex: openCursor() method
- IDBObjectStore: openKeyCursor() method
- IDBCursor: update() method
- IDBTransaction
- IndexedDB API
- Crypto: randomUUID() method
- IDBFactory: deleteDatabase() method
- ECMAScript 2024 Language Specification: Hosts and Implementations