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

CKTIS / JavaScript

IndexedDB : créer un index, insérer un enregistrement et le rechercher par index

Créez un index secondaire lors d’un changement de version, insérez sans écraser et recherchez par clé d’index plutôt que par clé primaire.

Version : Current web platform; runtime support varies

Syntaxe

store.createIndex(name, keyPath)
store.createIndex(name, keyPath, { unique, multiEntry })
store.add(value)
store.add(value, key)
store.index(name)

createIndex(), add() et index() sont des méthodes d’instance de IDBObjectStore dans l’API Web IndexedDB, pas dans ECMAScript. IndexedDB respecte la politique de même origine ; sa disponibilité dépend de l’environnement d’exécution et des réglages de stockage du navigateur.

store.createIndex(name, keyPath, options) renvoie immédiatement un IDBIndex, mais la modification du schéma ne devient définitive qu’à la validation de la transaction. Appelez cette méthode dans une transaction versionchange active, généralement lors de upgradeneeded, à la création de la base ou à l’augmentation de sa version. Le nom identifie l’index ; le chemin de clé détermine la clé d’index à partir de l’enregistrement sans y ajouter de champ. IndexedDB indexe les enregistrements existants et tient automatiquement l’index à jour.

unique et multiEntry valent false par défaut. unique: true interdit les clés d’index identiques dans des enregistrements distincts ; les doublons existants peuvent faire échouer la mise à niveau. multiEntry: true indexe les éléments valides d’une valeur de type tableau séparément, au lieu d’utiliser le tableau entier comme clé. Cette option est incompatible avec un tableau de chemins formant une clé composée (InvalidAccessError). Un nom d’index déjà utilisé déclenche immédiatement ConstraintError.

store.add(value[, key]) insère un clone structuré sans écraser de données. Utilisez une transaction readwrite ou versionchange active. Omettez key si la clé primaire est intégrée à la valeur ; fournissez-le si elle est externe et qu’il n’y a pas de générateur. En cas de succès, IDBRequest.result contient la clé primaire, mais seul l’événement complete de la transaction confirme la validation. Un doublon de clé primaire ou de clé d’index unique fait échouer la requête avec ConstraintError. put() peut remplacer un enregistrement, mais doit aussi respecter l’unicité de l’index.

store.index(name) renvoie l’IDBIndex existant, lié à la même transaction. Cette méthode ne crée pas d’index et ne lit pas d’enregistrement. Si le nom est introuvable, elle lève NotFoundError ; la casse compte. Dans une transaction active, index.get(key) demande le premier enregistrement correspondant à la clé d’index, et non à la clé primaire. Ne réutilisez pas cet objet pour lire après la fin de la transaction.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IndexedDB: insert and look up a contact</title>
</head>
<body>
<script>
(async () => {
  const { indexedDB, crypto } = window;
  const name = `cktis-index-${crypto.randomUUID()}`;
  const resultOf = (request) => new Promise((resolve, reject) => {
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
  const committed = (tx) => new Promise((resolve, reject) => {
    tx.oncomplete = () => resolve();
    tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
  });

  const open = indexedDB.open(name, 1);
  open.onupgradeneeded = () => {
    const store = open.result.createObjectStore('contacts', { keyPath: 'id' });
    store.createIndex('byEmail', 'email', { unique: true });
  };
  const db = await resultOf(open);
  let contact;
  try {
    const write = db.transaction('contacts', 'readwrite');
    write.objectStore('contacts').add({ id: 7, email: 'ada@example.test' });
    await committed(write);

    const read = db.transaction('contacts', 'readonly');
    const lookup = read.objectStore('contacts').index('byEmail').get('ada@example.test');
    await committed(read);
    contact = lookup.result;
  } finally {
    db.close();
    await resultOf(indexedDB.deleteDatabase(name));
  }
  console.log(JSON.stringify(contact));
})().catch((error) => console.error(error));
</script>
</body>
</html>

Résultat

{"id":7,"email":"ada@example.test"}

Hébergez le fichier HTML à une adresse HTTPS de confiance et ouvrez-le dans un navigateur où IndexedDB et `crypto.randomUUID()` sont disponibles. L’exemple crée une base distincte, recherche par `email` après validation de l’écriture, puis ferme et supprime la base avant d’afficher le résultat dans la console du navigateur.

Leçons associées

  • JavaScript · Leçon 31 · Avancé · Version : 4

Sources