CKTIS / JavaScript
IndexedDB : ajouter, lire, supprimer et remplacer des enregistrements
Utilisez `add()`, `getAll()`, `delete()` et `put()` pour manipuler des enregistrements par clé primaire, sans confondre la réussite d’une requête avec la validation de la transaction.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
store.add(value)
store.add(value, key)
store.getAll()
store.getAll(query)
store.getAll(query, count)
store.getAll(options)
store.delete(keyOrRange)
store.put(value)
store.put(value, key)Les méthodes add(), getAll(), delete() et put() appartiennent à l’interface IDBObjectStore d’IndexedDB, pas à ECMAScript. Le magasin d’objets s’obtient à partir d’une transaction. L’accès aux données suit la politique de même origine (schéma, hôte et port) ; la prise en charge dépend de l’environnement d’exécution.
add(value) sert uniquement à insérer : si la clé primaire existe déjà, la requête échoue avec ConstraintError. put(value) insère ou remplace toute la valeur associée à cette clé, sans fusionner les champs. Si la clé est intégrée à la valeur, omettez le second argument : keyPath indique où la trouver. Si la clé est externe, passez key en second argument, sauf si un générateur de clés activé doit la fournir. Les deux méthodes stockent une copie structurée de la valeur et placent la clé dans request.result en cas de réussite. Une valeur non clonable, comme une fonction, déclenche une exception synchrone DataCloneError.
getAll() place dans request.result un tableau de valeurs clonées, sans clés jointes séparément ; sans correspondance, le résultat est []. Par défaut, l’ordre est celui des clés primaires croissantes, pas celui des insertions. getAll(query, count) permet de choisir une clé ou un IDBKeyRange et de limiter le nombre de résultats avec un count positif. La forme getAll({ query, count, direction }) permet aussi de régler le sens, par exemple "prev" pour l’ordre décroissant ; vérifiez sa prise en charge dans les navigateurs ciblés.
delete(keyOrRange) supprime un enregistrement par clé primaire ou tous ceux d’un IDBKeyRange. En cas de réussite, le résultat vaut undefined, même si rien ne correspond. Cette méthode n’est pas l’opérateur JavaScript delete ; utilisez clear() pour vider le magasin.
Les quatre méthodes renvoient immédiatement un IDBRequest, pas une Promise. Le mode readonly suffit pour lire ; les écritures ordinaires exigent readwrite. Lancez les requêtes tant que la transaction est active, par exemple à sa création ou dans un gestionnaire d’événement de requête, et non après avoir attendu une réponse réseau. Par défaut, une erreur de requête interrompt la transaction et annule ses modifications. success concerne une seule requête ; l’événement complete confirme la validation de la transaction.
Exemples
void (async () => {
const { indexedDB, crypto } = globalThis;
if (!indexedDB || typeof crypto?.randomUUID !== 'function') {
throw new Error('Run this example on an HTTPS page in a browser with IndexedDB and crypto.randomUUID() available.');
}
const name = `cktis-idb-${crypto.randomUUID()}`;
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => {
open.result.createObjectStore('tasks', { keyPath: 'id' });
};
const db = await new Promise((resolve, reject) => {
open.onsuccess = () => resolve(open.result);
open.onerror = () => reject(open.error);
});
try {
const tx = db.transaction('tasks', 'readwrite');
const store = tx.objectStore('tasks');
store.add({ id: 2, title: 'Draft', tag: 'temporary' });
store.add({ id: 1, title: 'Remove me' });
const before = store.getAll();
store.put({ id: 2, title: 'Published' });
store.delete(1);
const after = store.getAll();
await new Promise((resolve, reject) => {
tx.oncomplete = () => resolve();
tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
});
console.log(JSON.stringify(before.result));
console.log(JSON.stringify(after.result));
} finally {
db.close();
const cleanup = indexedDB.deleteDatabase(name);
await new Promise((resolve, reject) => {
cleanup.onsuccess = () => resolve();
cleanup.onerror = () => reject(cleanup.error);
});
}
})().catch((error) => console.error(error));Résultat
[{"id":1,"title":"Remove me"},{"id":2,"title":"Draft","tag":"temporary"}]
[{"id":2,"title":"Published"}]Exécutez le code dans la console de développement d’une page HTTPS où IndexedDB et `crypto.randomUUID()` sont disponibles et où le stockage est autorisé. Après validation, la première ligne affiche les deux enregistrements dans l’ordre des clés. La seconde montre que `put()` n’a pas conservé `tag` et que `delete()` a supprimé l’enregistrement de clé `1`. Le code ferme la connexion et demande la suppression de la base temporaire.
Leçons associées
- JavaScript · Leçon 20 · Intermédiaire · Version : 3
Sources
- IDBObjectStore: add() method
- IDBObjectStore: getAll() method
- IDBObjectStore: delete() method
- IDBObjectStore: put() method
- IDBTransaction
- IDBTransaction: complete event
- IndexedDB key characteristics and basic terminology
- IDBDatabase: createObjectStore() method
- HTML Standard — Safe passing of structured data
- IDBFactory: open() method
- IDBFactory: deleteDatabase() method
- Crypto: randomUUID() method