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

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
IDBKeyRange
bound() static method
includes
lower
lowerBound() static method
lowerOpen
lowerBound() static method
upper
upperBound() static method
upperOpen
Available in workers

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Requires a vendor prefix or different name for use.
Has more compatibility info.

Voir aussi