IDBCursor
=========

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()` (en-US)

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()` (en-US)

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` (en-US) 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` (en-US) Lecture seule 

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

`IDBCursor.key` (en-US) 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` (en-US) 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
----------

**gecko 13:** 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 with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Manipuler IndexedDB
* Démarrer des transactions : `IDBDatabase`
* Manipuler des transactions : `IDBTransaction`
* Définir un intervalle de clés : `IDBKeyRange`
* Récupérer des données et les modifier : `IDBObjectStore`
* Manipuler des curseurs: `IDBCursor`
* Exemple de référence pour IndexedDB : To-do Notifications