IDBKeyRange

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.upperBound(x)
Toutes les clés < x IDBKeyRange.upperBound(x, true)
Toutes les clés ≥ y IDBKeyRange.lowerBound(y)
Toutes les clés > y IDBKeyRange.lowerBound(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.

Méthodes

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.includes()
Cette méthode renvoie un booléen qui indique si la clé passée en argument est contenue dans l'intervalle de clé.
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.

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

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.

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

Spécification État Commentaires
Indexed Database API
La définition de 'IDBKeyRange' dans cette spécification.
Recommendation Définition initiale.
Indexed Database API 2.0
La définition de 'IDBKeyRange' dans cette spécification.
Recommendation Ajout de includes().

Compatibilité des navigateurs

Fonctionnalité Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support simple 23 webkit
24 (sans préfixe)
38 (préfixes dépréciés)
57 (préfixes retirés)
(Oui) 10 moz
16.0 (16.0)
10, partial 15 7.1
Disponible dans les web workers (Oui) (sans préfixe)
38 (préfixes dépréciés)
57 (préfixes retirés)
(Oui) 37.0 (37.0) ? (Oui) ?
includes() 52.0 Pas de support 47.0 (47.0) ? 39 ?
Fonctionnalité Webview Android Chrome pour Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Support simple 23 webkit
24 (sans préfixe)
38 (préfixes dépréciés)
57 (préfixes retirés)
23 webkit
24 (sans préfixe)
38 (préfixes dépréciés)
57 (préfixes retirés)
(Oui) 22.0 (22.0) 10 22 8
Disponible dans les web workers (Oui) (sans préfixe)
38 (préfixes dépréciés)
57 (préfixes retirés)
(Oui) (sans préfixe)
38 (préfixes dépréciés)
57 (préfixes retirés)
(Oui) 37.0 (37.0) ? (Oui) ?
includes() 52.0 52.0 Pas de support ? ? ? ?

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, gadgino, Goofy, jpmedley
 Dernière mise à jour par : SphinxKnight,