IDBIndex.openCursor()

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

Voir aussi