IDBKeyRange

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.

L'interface IDBKeyRange de l'API IndexedDB représente un intervalle continue sur un type de donnée utilisé pour représenter des clés. Les enregistrements peuvent être récupérés depuis des objets IDBObjectStore et IDBIndex grâce à des clés ou à des intervalles de clé. Il est possible de préciser les bornes inférieure et supérieure de l'intervalle. Si les clés sont des chaînes de caractères, on pourrait ainsi parcourir l'ensemble des valeurs pour l'intervalle A–Z.

Un intervalle de clé peut être une seule valeur ou un intervalle avec des bornes inférieure et supérieure. Si l'intervalle possède ces deux bornes, il est dit borné. S'il n'a aucune borne, il est non-borné. Un intervalle de clé borné peut être ouvert (les bornes sont exclues) ou fermé (les bornes sont inclues). Pour récupérer les différentes clés d'un intervalle donné, on peut utiliser les fragments de code suivants :

Intervalle Code
Toutes les clés ≥ x IDBKeyRange.lowerBound(x)
Toutes les clés > x IDBKeyRangelowerBound(x, true)
Toutes les clés ≤ y IDBKeyRange.upperBound(y)
Toutes les clés < y IDBKeyRange.upperBound(y, true)
Toutes les clés ≥ x && ≤ y IDBKeyRange.bound(x, y)
Toutes les clés > x &&< y IDBKeyRange.bound(x, y, true, true)
Toutes les clés > x && ≤ y IDBKeyRange.bound(x, y, true, false)
Toutes les clés ≥ x &&< y IDBKeyRange.bound(x, y, false, true)
La clé = z IDBKeyRange.only(z)

Une clé est contenue dans un intervalle de clé lorsque les conditions suivantes sont réunies :

  • La borne inférieure de l'intervalle de clé est :

    • undefined
    • Inférieure à la valeur de la clé
    • Égal à la valeur de la clé si lowerOpen est false (l'intervalle est fermé à gauche)

  • La borne supérieure de l'intervalle de clé est :

    • undefined
    • Supérieure à la valeur de la clé
    • Égal à la valeur de la clé si upperOpen vaut false (l'intervalle est fermé à droite)

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

Propriétés

IDBKeyRange.lower Lecture seule

Cette propriété fournit la borne inférieure de l'intervalle de clé.

IDBKeyRange.upper Lecture seule

Cette propriété fournit la borne supérieure de l'intervalle de clé.

IDBKeyRange.lowerOpen Lecture seule

Cette méthode renvoie false si la borne inférieure est contenue dans l'intervalle de clé (autrement dit elle permet de vérifier si l'intervalle est ouvert à gauche).

IDBKeyRange.upperOpen Lecture seule

Cette méthode renvoie false si la borne supérieure est contenue dans l'intervalle de clé (autrement dit elle permet de vérifier si l'intervalle est ouvert à droite).

Méthodes

Méthodes statiques

IDBKeyRange.bound()

Cette méthode permet de créer un nouvel intervalle de clé avec une borne inférieure et une borne supérieure.

IDBKeyRange.only()

Cette méthode crée un nouvel intervalle de clé qui ne contient qu'une valeur.

IDBKeyRange.lowerBound()

Cette méthode crée un nouvel intervalle de clé avec une borne inférieure.

IDBKeyRange.upperBound()

Cette méthode crée un nouvel intervalle de clé avec une borne supérieure.

Méthodes des instances

IDBKeyRange.includes()

Cette méthode renvoie un booléen qui indique si la clé passée en argument est contenue dans l'intervalle de clé.

Exemples

Dans l'exemple qui suit, on montre comment utiliser un intervalle de clé. Ici, on déclare un objet keyRangeValue qui représente un intervalle pour les valeurs entre "A" et "F". On ouvre une transaction grâce à IDBTransaction, on ouvre également un magasin d'objets puis un curseur avec la méthode IDBObjectStore.openCursor pour lequel on indique que keyRangeValue est l'intervalle de clé à considérer. Cela signifie que le curseur récupèrera uniquement les enregistrements pour lesquels les clés sont contenues dans cet intervalle. Cet intervalle est fermé, il inclut les valeur "A" and "F" (on n'a pas indiqué que ces bornes étaient ouvertes). Si on avait utilisé IDBKeyRange.bound("A", "F", true, true);, l'intervalle serait ouvert et ne contiendrait pas "A" ou "F" mais uniquement les valeurs intermédiaires.

js
function displayData() {
  var keyRangeValue = IDBKeyRange.bound("A", "F");

  var transaction = db.transaction(["fThings"], "readonly");
  var objectStore = transaction.objectStore("fThings");

  objectStore.openCursor(keyRangeValue).onsuccess = function (event) {
    var cursor = event.target.result;
    if (cursor) {
      var listItem = document.createElement("li");
      listItem.innerHTML =
        "<strong>" + cursor.value.fThing + "</strong>, " + cursor.value.fRating;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log("Les éléments ont été affichés.");
    }
  };
}

Note : Pour un exemple complet qui utilise les intervalles de clé, vous pouvez consulter le dépôt GitHub IDBKeyRange-example (ainsi que la démonstration associée).

Spécifications

Specification
Indexed Database API 3.0
# keyrange

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi