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

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

Fontes