CKTIS / JavaScript
IndexedDB: aggiungere, leggere, eliminare e sostituire record
Usa `add()`, `getAll()`, `delete()` e `put()` per lavorare con i record tramite la chiave primaria, distinguendo il successo di una richiesta dal commit della transazione.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
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)I metodi add(), getAll(), delete() e put() appartengono all’interfaccia IDBObjectStore di IndexedDB, non a ECMAScript. L’archivio di oggetti si ottiene da una transazione. L’accesso ai dati segue la regola della stessa origine (schema, host e porta); il supporto dipende dall’ambiente di esecuzione.
add(value) serve solo a inserire: se la chiave primaria esiste già, la richiesta fallisce con ConstraintError. put(value) inserisce o sostituisce l’intero valore associato alla chiave; non unisce i campi. Se la chiave è interna al valore, ometti il secondo argomento: keyPath indica dove trovarla. Se la chiave è esterna, passa key come secondo argomento, a meno che debba fornirla un generatore di chiavi abilitato. Entrambi i metodi memorizzano una copia strutturata del valore e, in caso di successo, impostano request.result alla chiave. Un valore non clonabile, come una funzione, causa un DataCloneError sincrono.
getAll() imposta request.result a un array di valori clonati, senza chiavi allegate separatamente; se non ci sono corrispondenze, il risultato è []. L’ordine predefinito è quello crescente delle chiavi primarie, non quello d’inserimento. Con getAll(query, count) puoi selezionare una chiave o un IDBKeyRange e limitare i risultati con un count positivo. La forma getAll({ query, count, direction }) permette anche di specificare la direzione, per esempio "prev" per l’ordine decrescente; verificane il supporto nei browser di destinazione.
delete(keyOrRange) elimina un record tramite la chiave primaria o tutti quelli compresi in un IDBKeyRange. Il risultato di una richiesta riuscita è undefined, anche se non c’erano corrispondenze. Il metodo non è l’operatore JavaScript delete; usa clear() per svuotare l’archivio.
Tutti e quattro i metodi restituiscono subito un IDBRequest, non una Promise. Per leggere basta readonly; le normali scritture richiedono readwrite. Accoda le richieste mentre la transazione è attiva, per esempio quando la crei o in un gestore di eventi della richiesta, non dopo aver atteso una risposta di rete. Per impostazione predefinita, un errore di richiesta interrompe la transazione e annulla le sue modifiche. success riguarda una singola richiesta; complete conferma il commit della transazione.
Esempi
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));Risultato
[{"id":1,"title":"Remove me"},{"id":2,"title":"Draft","tag":"temporary"}]
[{"id":2,"title":"Published"}]Esegui il codice nella console per sviluppatori di una pagina HTTPS in cui IndexedDB e `crypto.randomUUID()` siano disponibili e l’accesso allo spazio di archiviazione sia consentito. Dopo il commit, la prima riga mostra entrambi i record in ordine di chiave. La seconda mostra che `put()` non ha conservato `tag` e che `delete()` ha eliminato il record con chiave `1`. Il codice chiude la connessione e richiede l’eliminazione del database temporaneo.
Lezioni correlate
- JavaScript · Lezione 20 · Intermedio · Versione: 3
Fonti
- 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