IDBCursor

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 IDBCursor de l' API IndexedDB représente un curseur pour traverser ou itérer sur plusieurs enregistrements dans une base de données.

Le curseur possède une source qui indique l'index ou le magasin d'objets sur lequel il itère. Il est décrit par une position dans cet intervalle et par une direction dans laquelle il se déplace : dans l'ordre des clés d'enregistrement suivant le sens donné au curseur (montant ou descendant). Le curseur permet à une application de traiter de façon asynchrone tous les enregistrements de sa plage.

On peut avoir autant de curseurs qu'on souhaite en même temps. Ce sera toujours le même objet IDBCursor qui représentera un curseur donné. Les opérations sont effectuées à l'intérieur de l'index ou du magasin d'objet.

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

Méthodes

IDBCursor.advance()

Définit le nombre d'itérations vers l'avant.

IDBCursor.continue()

Avance le curseur sur la position suivante le long de sa direction, jusqu'à l'élément dont la clé correspond au paramètre (optionnel) passé à la fonction.

IDBCursor.delete()

Retourne un objet IDBRequest, et, dans un thread séparé, supprime l'enregistrement à la position du curseur, sans changer la position du curseur. Ceci peut être utilisé pour supprimer des enregistrements spécifiques.

IDBCursor.update()

Retourne un objet IDBRequest, et, dans un thread séparé, met à jour la valeur à la position actuelle du curseur dans le magasin d'objets. Ceci peut être utilisé pour mettre à jour des enregistrements spécifiques.

Propriétés

IDBCursor.source Lecture seule

Renvoie le IDBObjectStore ou IDBIndex sur lequel le curseur itère. Cette fonction ne retourne jamais null et ne déclenche pas d'exception, même dans les cas ou le curseur est en train d'itérer, s'il a itéré en dehors la plage ou si la transaction n'est pas active.

IDBCursor.direction Lecture seule

Renvoie la direction de parcours du curseur. Voir le paragraphe suivant, Constantes, pour les valeurs possibles.

IDBCursor.key Lecture seule

Renvoie la clé de l'enregistrement à la position du curseur ou undefined si le curseur est en dehors de la plage. La clé peut être de n'importe quel type de données.

IDBCursor.primaryKey Lecture seule

Renvoie la clé primaire effective actuelle du curseur ou undefined si le curseur est actuellement itéré ou a itéré en dehors de sa plage. La clé primaire du curseur peut être de tout type de données.

Constantes

Obsolète: Cette fonctionnalité a été supprimée des standards du Web. Bien que quelques navigateurs puissent encore la supporter, elle est en cours d'éradication. Ne l'utilisez ni dans d'anciens projets, ni dans de nouveaux. Les pages et applications Web l'utilisant peuvent cesser de fonctionner à tout moment.

Attention : Ces constantes ne sont plus disponibles - elles ont été retirées depuis Gecko 25. Les valeurs équivalentes en chaînes de caractères devraient être utilisées à la place (cf. bug Firefox 891944).

Constante Valeur Description
NEXT

"next"

Le curseur indique tous les enregistrements, y compris les doublons. Il commence à la limite inférieure de la plage de clé et se déplace vers le haut (en itérant dans l'ordre des clés).
NEXTUNIQUE

"nextunique"

Le curseur indique tous les enregistrements, à l'exclusion des doublons. Si plusieurs enregistrements existent avec la même clé, seule la première itération est récupérée. Il commence à la limite inférieure de la plage de clé et se déplace vers le haut.
PREV

"prev"

Le curseur indique tous les enregistrements, y compris les doublons. Il commence à la limite supérieure de la plage de clé et se déplace vers le bas (en itérant dans l'ordre inverse des clés).
PREVUNIQUE

"prevunique"

Le curseur indique tous les enregistrements, à l'exclusion des doublons. Si plusieurs enregistrements existent avec la même clé, seule la première itération est récupéré. Il commence à la limite supérieure de la plage de clé et se déplace vers le bas.

Exemple

Dans ce fragment simple, nous créons une transaction, récupérons un magasin d'objets, puis utilisons un curseur pour parcourir tous les enregistrements du magasin d'objets. Le curseur ne nous oblige pas à sélectionner les données basées sur une clé, nous pouvons simplement travailler sur tout les enregistrements. Notez également que dans chaque itération de la boucle, vous pouvez récupérer les données de l'enregistrement en cours sous l'objet curseur à l'aide curseur.value.toto. Pour un exemple de travail complet, voir notre exemple IDBCursor (l'exemple en live).

js
function afficheDonnee() {
  var transaction = db.transaction(["grandListAlbum"], "readonly");
  var objectStore = transaction.objectStore("grandListAlbum");

  objectStore.openCursor().onsuccess = function (event) {
    var curseur = event.target.result;
    if (curseur) {
      var listItem = document.createElement("li");
      listItem.innerHTML =
        curseur.value.titreAlbum + ", " + curseur.value.annee;
      list.appendChild(listItem);

      curseur.continue();
    } else {
      console.log("Entrées tous affichés.");
    }
  };
}

Spécifications

Specification
Indexed Database API 3.0
# cursor-interface

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi