CKTIS / JavaScript
IDBRequest: resultado, erro e funções de tratamento de eventos
Lê `result` quando um pedido de IndexedDB é bem-sucedido e `error` quando falha. O sucesso de um pedido não significa que a transação tenha sido confirmada.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
// Read-only members; do not read either while readyState is "pending".
// request.result
// request.error
request.onsuccess = (event) => { /* read request.result */ };
request.onerror = (event) => { /* read request.error */ };
// Alternative registration; event names omit the "on" prefix.
request.addEventListener("success", handleSuccess);
request.addEventListener("error", handleError);IDBRequest é um objeto de pedido de IndexedDB, não uma promessa (Promise). IndexedDB é uma API Web, não faz parte de ECMAScript 2024 e a sua disponibilidade depende do ambiente de execução. Enquanto readyState for "pending", ler qualquer uma das propriedades só de leitura result ou error lança uma DOMException chamada InvalidStateError. O estado "done" permite ler estas propriedades, mas não garante que o pedido tenha sido bem-sucedido. Um IDBOpenDBRequest pode indicar "done" durante upgradeneeded, antes do evento final success ou error.
Atribui funções a request.onsuccess e request.onerror para tratar success e error, respetivamente. Uma nova atribuição substitui a função anterior; usa addEventListener() com o nome do evento sem on para adicionar ouvintes independentes. Em caso de sucesso, lê request.result: o valor depende da operação. Por exemplo, add() fornece a chave através de result, enquanto get() pode ter sucesso com undefined se a chave não existir. Em caso de sucesso, request.error é null; em caso de falha, contém uma DOMException e request.result é undefined. Um try...catch à volta da chamada pode intercetar uma exceção síncrona dessa chamada, mas não uma falha posterior do pedido.
O evento success não se propaga para cima e não pode ser cancelado. Num pedido que pertence a uma transação, error propaga-se para cima e, por omissão, provoca o abandono da transação. Chama event.preventDefault() na função que trata um erro esperado e recuperável para impedir esse abandono por omissão. O pedido continua a ter falhado e o evento continua a propagar-se.
Uma escrita bem-sucedida não significa que a transação tenha sido confirmada. Submete outros pedidos enquanto a transação estiver ativa, por exemplo, diretamente numa função de tratamento de eventos do pedido. Na transação, escuta complete para detetar a confirmação e abort para detetar a reversão das alterações.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IDBRequest: success and error</title>
</head>
<body>
<p>Open the browser developer console to see the output.</p>
<script>
(() => {
const name = `cktis-idbrequest-${window.crypto.randomUUID()}`;
const open = window.indexedDB.open(name, 1);
open.onupgradeneeded = () => open.result.createObjectStore("items");
open.onerror = () => console.error("open:", open.error.name);
open.onsuccess = () => {
const db = open.result;
const tx = db.transaction("items", "readwrite");
const store = tx.objectStore("items");
function cleanup() {
db.close();
const deletion = window.indexedDB.deleteDatabase(name);
deletion.onerror = () => console.error("cleanup:", deletion.error.name);
}
tx.oncomplete = () => {
console.log("transaction: complete");
cleanup();
};
tx.onabort = () => {
console.error("transaction: aborted", tx.error?.name);
cleanup();
};
const first = store.add("first", 1);
first.onsuccess = () => console.log(`success: ${first.result}`);
const duplicate = store.add("second", 1);
duplicate.onerror = (event) => {
const { name } = duplicate.error;
if (name === "ConstraintError") event.preventDefault();
console.log(`error: ${name}`);
};
};
})();
</script>
</body>
</html>Resultado
success: 1 error: ConstraintError transaction: complete
Guarda o exemplo num ficheiro HTML e disponibiliza-o por HTTPS. Abre a página num navegador com IndexedDB e `crypto.randomUUID()` disponíveis e verifica a saída na consola de programador. O primeiro `add()` fornece a chave `1` através de `result`; o segundo falha com `ConstraintError`. `preventDefault()` impede que esse erro provoque o abandono da transação, que pode assim emitir `complete`. Ao terminar a transação, o código fecha a ligação e pede a eliminação da base de dados criada para esta execução.
Lições relacionadas
- JavaScript · Lição 31 · Avançado · Versão: 4