Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

IDBRequest : résultat, erreur et gestionnaires d’événements

Lisez `result` si une requête IndexedDB réussit et `error` si elle échoue. La réussite d’une requête ne signifie pas que sa transaction a été validée.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

// 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 est un objet de requête IndexedDB, pas une promesse (Promise). IndexedDB est une API Web, et non une fonctionnalité d’ECMAScript 2024 ; sa disponibilité dépend de l’environnement d’exécution. Tant que readyState vaut "pending", la lecture de l’une des propriétés en lecture seule result ou error lève une DOMException nommée InvalidStateError. L’état "done" permet de lire ces propriétés, mais ne garantit pas la réussite de la requête. Un IDBOpenDBRequest peut être à l’état "done" pendant upgradeneeded, avant l’événement final success ou error.

Affectez des fonctions à request.onsuccess et request.onerror pour traiter respectivement success et error. Une nouvelle affectation remplace le gestionnaire précédent ; addEventListener() permet d’ajouter des écouteurs distincts avec le nom d’événement sans on. En cas de succès, lisez request.result : sa valeur dépend de l’opération. Par exemple, add() fournit la clé via result, tandis que get() peut réussir avec undefined si la clé est absente. En cas de succès, request.error vaut null ; en cas d’échec, il contient une DOMException et request.result vaut undefined. Un try...catch autour de l’appel intercepte les exceptions synchrones de cet appel, pas un échec ultérieur de la requête.

L’événement success ne remonte pas et n’est pas annulable. Pour une requête dans une transaction, error remonte et entraîne par défaut l’abandon de la transaction. Appelez event.preventDefault() dans le gestionnaire d’une erreur attendue dont vous pouvez vous remettre pour empêcher cet abandon par défaut. La requête reste en échec et l’événement continue de remonter.

La réussite d’une écriture ne signifie pas que la transaction a été validée. Soumettez les requêtes suivantes pendant que la transaction est active, par exemple directement dans un gestionnaire d’événement de requête. Sur la transaction, écoutez complete pour détecter la validation et abort pour détecter l’annulation des modifications.

Exemples

<!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>

Résultat

success: 1
error: ConstraintError
transaction: complete

Enregistrez l’exemple dans un fichier HTML et servez-le en HTTPS. Ouvrez la page dans un navigateur où IndexedDB et `crypto.randomUUID()` sont disponibles, puis consultez la sortie dans la console de développement. Le premier `add()` fournit la clé `1` via `result` ; le second échoue avec `ConstraintError`. `preventDefault()` empêche cette erreur d’entraîner l’abandon de la transaction, qui peut donc émettre `complete`. Une fois la transaction terminée, le code ferme la connexion et demande la suppression de la base créée pour cette exécution.

Leçons associées

  • JavaScript · Leçon 31 · Avancé · Version : 4

Sources