Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

IDBIndex — interroger un index IndexedDB

IDBIndex expose les enregistrements d’un magasin d’objets au moyen d’une clé secondaire. Compare la récupération d’un tableau avec getAll() à l’itération d’un curseur avec openCursor(), et distingue les clés d’index des clés primaires.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

const index = transaction.objectStore(storeName).index(indexName);
const valuesRequest = index.getAll(query, count);
const cursorRequest = index.openCursor(query, "next");

IDBIndex est une référence à l’index secondaire d’un magasin d’objets IndexedDB, et non un constructeur à utiliser directement. Créez l’index avec createIndex() pendant upgradeneeded, puis récupérez-le avec store.index(name) dans une transaction. L’index est automatiquement mis à jour avec le magasin.

IDBIndex.getAll(query, count) renvoie un IDBRequest, et non une Promise. Son résultat est un tableau de valeurs du magasin, ou [] en l’absence de correspondance. query accepte une clé d’index ou un IDBKeyRange ; s’il est omis, toutes les entrées correspondent. Le paramètre facultatif count limite le nombre de résultats. S’il vaut 0 ou s’il est omis, toutes les entrées correspondantes sont renvoyées. Le tri est croissant selon la clé d’index, puis la clé primaire.

IDBIndex.openCursor(query, direction) renvoie également un IDBRequest. Dans success, lisez le curseur, ou null lorsqu’il ne reste aucun résultat ; continue() lance l’étape suivante. cursor.key est la clé d’index, cursor.primaryKey la clé du magasin et cursor.value l’enregistrement. La direction par défaut est "next" ; les autres choix sont "prev", "nextunique" et "prevunique".

Un curseur permet un traitement progressif ; getAll() matérialise tout le tableau de résultats. Lancez les requêtes tant que la transaction est active ; n’intercalez pas de await sans rapport entre elles. L’exemple utilise la syntaxe IndexedDB 2.0, sans la forme plus récente des options de getAll(). Vérifiez le navigateur cible : disposer de Node 24 ne prouve pas la prise en charge de cette API Web.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IDBIndex: querying a secondary key</title>
</head>
<body>
  <h1>Querying an IndexedDB index</h1>
  <script>
    (() => {
      const name = 'cktis-index-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
      const report = error => console.log(error.name === 'SecurityError'
        ? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
      let factory, opening;
      try {
        factory = window.indexedDB;
        if (!factory) {
          console.log('IndexedDB unavailable: API missing');
          return;
        }
        opening = factory.open(name, 1);
      } catch (error) {
        report(error);
        return;
      }
      let created = false;
      opening.onerror = () => report(opening.error);
      opening.onupgradeneeded = () => {
        created = true;
        const store = opening.result.createObjectStore('tokens', { keyPath: 'id' });
        store.createIndex('byColor', 'color');
        store.add({ id: 2, color: 'blue', token: 'square' });
        store.add({ id: 1, color: 'blue', token: 'circle' });
        store.add({ id: 3, color: 'red', token: 'triangle' });
      };
      opening.onsuccess = () => {
        const db = opening.result;
        if (!created) {
          db.close();
          console.log('Fixture name already in use');
          return;
        }
        const tx = db.transaction('tokens', 'readonly');
        const index = tx.objectStore('tokens').index('byColor');
        const all = index.getAll('blue');
        const scan = index.openCursor('blue');
        const rows = [];
        scan.onsuccess = () => {
          const cursor = scan.result;
          if (cursor) {
            rows.push([cursor.key, cursor.primaryKey, cursor.value.token]);
            cursor.continue();
          }
        };
        const cleanup = () => {
          db.close();
          factory.deleteDatabase(name);
        };
        tx.oncomplete = () => {
          console.log(JSON.stringify(all.result.map(record => record.token)));
          console.log(JSON.stringify(rows));
          cleanup();
        };
        tx.onabort = () => {
          report(tx.error);
          cleanup();
        };
      };
    })();
  </script>
</body>
</html>

Résultat

When IndexedDB access is allowed and the query succeeds, both lines show matches for the index key "blue" in ascending primary-key order:
["circle","square"]
[["blue",1,"circle"],["blue",2,"square"]]

If the browser denies IndexedDB access with a SecurityError, the example logs instead:
IndexedDB unavailable: SecurityError

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources