IDBRequest

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2021.

L'interface IDBRequest de l'API IndexedDB donne accès par ses gestionnaires d'événements aux résultats des requêtes asynchrones sur la base de données, les magasins d'objets ou les index. Chaque opération d'écriture ou lecture sur la base de données utilise une requête.

Cet objet IDBRequest ne contient aucune information sur le résultat de l'opération, mais dès qu'une information est disponible un événement est déclenché. L'objet IDBRequest utilise ses gestionnaires d'événements pour le capter et mettre l'information à disposition.

Toute les opération asynchrone retourne immédiatement une instance IDBRequest avec une propriété readyState défini à 'pending' qui passe à 'done' lorsque la requête réussie ou échoue. Quand l'état passe à done, chaque requête retourne result et error, et un évènement est envoyé sur la requête. Quand l'état est sur pending, chaque accès à result ou error lève une exception InvalidStateError.

Pour faire simple, chaque méthode asynchrome retourne un objet de requête. Si l'opération réussi, le résultat est disponible dans la propriété result et un évènement success est lancé (IDBRequest.onsuccess). Si une erreur est rencontrée, une exeption est disponible dans la propriété error et un évènement error est lancé (IDBRequest.onerror).

L'interface IDBOpenDBRequest est dérivé de IDBRequest.

Note : Cette fonctionnalité est disponible via les Web Workers.

EventTarget IDBRequest

Propriétés

Hérite des propriétés de EventTarget.

result Lecture seule

La propriété result de l'interface IDBRequest renvoie le résultat de la requête. Si la requête est en cours, échoue ou que le résultat n'est pas disponible, l'exception InvalidStateError est levée.

error Lecture seule

La propriété error de l'interface IDBRequest indique le code de l'erreur survenue durant le traitement de la requête. Si la requête est en cours l'exception InvalidStateError est levée.

source Lecture seule

La propriété source de l'interface IDBRequest renvoie la source de la requête, tel qu'un index, un magasin d'ojets ou null s'il n'y a pas de source (lors de l'appel indexedDB.open par exemple).

transaction Lecture seule

La propriété transaction de l'interface IDBRequest renvoie la transaction dans laquelle on fait la requête. La propriété peut renvoyer null si requête se fait sans transaction, comme un objet IDBRequest renvoyé par IDBFactory.open dans ce cas on est juste connecté à la base de données.

readyState Lecture seule

La propriété readyState de l'interface IDBRequest renvoie l'état de la requête. Chaque requête débute avec un statut pending et passe au statut done quand la requête réussie ou échoue.

Méthodes

Pas de méthodes spécifiques, mais hérite des méthodes de EventTarget.

Gestionnaire d'événement

On peut écouter les évènement avec addEventListener() ou bien en assignant un gestionnaire d'évènement à la propriété oneventname de cette interface.

onerror

Le gestionnaire d'événement onerror de l'interface IDBRequest capte l'événement error, déclenché quand une requête renvoie une erreur.

onsuccess

Le gestionnaire d'événement onsuccess de l'interface IDBRequest capte l'événement success, déclenché quand la requête réussie.

Exemple

Dans l'exemple suivant, on ouvre une base de données et on fait une requête. Les gestionnaires d'événement onsuccess et onerror sont inclus. Pour un exemple de travail complet, voir notre application To-do Notifications (voir l'exemple en direct).

js
var db;

// Ouvre une base de données.
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

// Ces deux gestionnaires d'événement interviennent quand la dase de
// de données s'ouvre ou non.
DBOpenRequest.onerror = function (event) {
  note.innerHTML += "<li>Error loading database.</li>";
};

DBOpenRequest.onsuccess = function (event) {
  note.innerHTML += "<li>Database initialised.</li>";

  // Affecte le resutat de l'ouverture à la variable.
  db = DBOpenRequest.result;
};

Spécifications

Specification
Indexed Database API 3.0
# request-api

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi