Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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