IDBIndex.openKeyCursor()
========================

La méthode **`openKeyCursor()`** de `IDBIndex` renvoie un objet `IDBRequest` et, dans un *thread* séparé, crée un curseur sur l'intervalle de clé passé en argument pour l'index courant.

Cette méthode positionne le curseur sur la clé appropriée, dans la direction indiquée :

* si l'intervalle de clé n'est pas défini ou s'il est nul, l'intervalle englobera l'ensemble des clés
* si au moins une clé correspond à l'intervalle de clés, un évènement `success` est déclenché pour la requête qui est renvoyée. La propriété `result` de cet évènement contiendra un objet `IDBCursor` dont la propriété `value` correspond à l'enregistrement qui a été traduit.
* Si aucun intervalle ne correspond à l'intervalle indiqué, un évènement `error` est déclenché pour la requête.

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

Syntaxe
-------


```js
var monIndex = objectStore.index("index");
var request = monIndex.openKeyCursor(keyRange, direction);
```

### Paramètres

`keyRange` Facultatif

L'`intervalle de clé` sur lequel se déplace le curseur. On peut passer un clé seule qui sera alors considéré comme une `intervalle seule`. Par défaut le curseur se déplace sur l'ensemble des clés de l'index.

`direction` Facultatif

La `direction` (en-US) du `curseur` qui défini le sens d'itération. par défaut "next".

### Valeur de retour

Un objet `IDBRequest` sur lequel on peut écouter les évènements associés à l'opération lancée par la méthode.

### Exceptions

Cette méthode peut lever une exception :

| Type d'exception | Description |
| --- | --- |
| TransactionInactiveError | 
 La transaction pour cet index `IDBIndex` 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 `IDBIndex` 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 itère sur l'ensemble des enregistrements pour en insérer leur clé dans un tableau HTML. En utilisant la méthode `IDBIndex.openKeyCursor` qui travaille de la même façon que la méthode `IDBObjectStore.openKeyCursor` 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) {
      // cursor.key la clé de l'enregistrement à la position du curseur
      // il n'y as pas de cursor.value contrairement à openCursor()

      var tableRow = document.createElement("tr");
      tableRow.innerHTML = "<td>" + cursor.key + "</td>";
      tableEntry.appendChild(tableRow);

      //on relance la requête pour la position suivante du curseur
      cursor.continue();
    } else {
      console.log("Toutes les clé 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-openkeycursor① |

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`