IDBIndex.openCursor()
=====================

La méthode **`openCursor()`** de l'interface `IDBIndex` renvoie un objet `IDBRequest` et, dans un *thread* séparé, crée un curseur sur l'intervalle de clé fourni en argument.

La méthode la positionne le curseur de façon approprié, selon la direction indiquée :

* Si aucun intervalle de clé n'est spécifié ou qu'il vaut `null`, l'intervalle résultant contiendra l'ensemble des enregistrements
* L'évènement `success` est toujours déclenché :
    + Si un enregistrement est trouvé la propriété `result` de l'évènement contient le nouvel objet `IDBCursor` et la valeur (`value`) de ce curseur est un clône de la valeur référencée
    + Si aucun enregistrement n'est trouvé la propriété `result` de l'évènement vaudra `null`.

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

Syntaxe
-------


```js
var request = myIndex.openCursor(keyRange, direction);
```

### Paramètres

`keyRange` Facultatif

L'intervalle de clé (`IDBKeyRange`) sur lequel se déplace le curseur. Si aucun argument n'est passé, la valeur par défaut sera un intervalle qui englobe tous les enregistrements du magasin d'objets.

`direction` Facultatif

La direction dans laquelle se déplace le curseur (la propriété `direction` de l'objet `IDBCursor.direction` (en-US)). La valeur par défaut est `"next"`.

### Valeur de retour

Un objet `IDBRequest` sur lequel les évènements associés à l'opération seront déclenchés.

### Exceptions

Cette méthode peut déclencher une `DOMException` dont le type peut être l'un des suivant :

| Type d'exception | Description |
| --- | --- |
| TransactionInactiveError | La transaction pour cet index est inactive. |
| `TypeError` | La valeur du paramètre pour la direction est invalide. |
| DataError | La clé ou l'intervalle de clé fourni contient une clé invalide. |
| `InvalidStateError` | L'index a été supprimé ou déplacé. |

Exemple
-------

Dans l'exemple suivant, on ouvre une transaction puis un magasin d'objet et enfin l'index `lName`.

Ensuite, on parcourt les enregistrements pour insérer les données dans un tableau HTML. En utilisant la méthode `IDBIndex.openCursor` qui travaille de la même façon que la méthode `IDBObjectStore.openCursor` de l'`accès` au magasin d'objet sauf que les enregistrements sont renvoyés dans l'ordre de l'index et non celui du magasin d'objet.


```js
function displayDataByIndex() {
  tableEntry.innerHTML = "";

  //ouvre un transaction
  var transaction = db.transaction(["contactsList"], "readonly");
  //accés au magasin d'objet
  var objectStore = transaction.objectStore("contactsList");

  //on récupère l'index
  var myIndex = objectStore.index("lName");

  //un curseur qui itère sur l'index
  var request = myIndex.openCursor();
  request.onsuccess = function (event) {
    var cursor = request.result;
    if (cursor) {
      var tableRow = document.createElement("tr");
      tableRow.innerHTML =
        "<td>" +
        cursor.value.id +
        "</td>" +
        "<td>" +
        cursor.value.lName +
        "</td>" +
        "<td>" +
        cursor.value.fName +
        "</td>" +
        "<td>" +
        cursor.value.jTitle +
        "</td>" +
        "<td>" +
        cursor.value.company +
        "</td>" +
        "<td>" +
        cursor.value.eMail +
        "</td>" +
        "<td>" +
        cursor.value.phone +
        "</td>" +
        "<td>" +
        cursor.value.age +
        "</td>";
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("Tous les enregistrements ont été affichés.");
    }
  };
}
```


**Note :** pour un exemple fonctionnel complet, voir notre application To-do (exemple).

Spécifications
--------------

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbindex-opencursor② |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

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

* Utiliser IndexedDB
* Initier une connexion : `IDBDatabase`
* Utiliser les transactions : `IDBTransaction`
* Définir un intervalle de clés : `IDBKeyRange`
* Récupérer et modifier les données : `IDBObjectStore`
* Utiliser les curseurs `IDBCursor`
* Exemple de référence : To-do Notifications (exemple *live*).