IDBIndex.openKeyCursor()

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.

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 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

Voir aussi