Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

IndexedDB: creare archivi di oggetti e aprire transazioni

Usa `createObjectStore()` per cambiare lo schema durante un aggiornamento e `transaction()` per leggere o scrivere record negli archivi esistenti.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

db.createObjectStore(name) → IDBObjectStore
db.createObjectStore(name, options) → IDBObjectStore

db.transaction(storeNames) → IDBTransaction
db.transaction(storeNames, mode) → IDBTransaction
db.transaction(storeNames, mode, options) → IDBTransaction

IDBDatabase rappresenta una connessione aperta a IndexedDB. db.createObjectStore(name, options) restituisce subito un nuovo IDBObjectStore, ma funziona solo in una transazione versionchange attiva. IndexedDB avvia la transazione quando indexedDB.open() crea il database o lo apre con una versione superiore. Modifica lo schema in upgradeneeded. Una connessione aperta in un’altra scheda può bloccare l’aggiornamento: la richiesta di apertura genera blocked e la vecchia connessione può chiamare close() in risposta a versionchange.

Il keyPath facoltativo indica da dove estrarre la chiave dal valore, per esempio da id. Un array di percorsi definisce una chiave composta; in assenza di un percorso, la chiave viene memorizzata separatamente. autoIncrement è false per impostazione predefinita; true attiva un generatore di chiavi, ma non si può combinare con una stringa vuota o un array come keyPath (InvalidAccessError). Un nome di archivio duplicato causa ConstraintError, un percorso non valido causa SyntaxError e una chiamata senza transazione di aggiornamento causa InvalidStateError.

db.transaction(storeNames, mode, options) restituisce subito una IDBTransaction il cui ambito è definito da un singolo nome di archivio passato come stringa oppure da un iterabile non vuoto di nomi di archivi esistenti, come un array o un Set. Accedi a uno di questi archivi con tx.objectStore(name). La modalità predefinita "readonly" consente solo la lettura; "readwrite" consente anche la scrittura. Qui non puoi scegliere "versionchange" (TypeError). Un archivio sconosciuto causa NotFoundError, un elenco vuoto causa InvalidAccessError e una connessione chiusa o in chiusura causa InvalidStateError. L’opzione options.durability ("default", "strict", "relaxed") indica la preferenza di durabilità al commit; verifica il supporto dei browser di destinazione.

Accoda richieste solo mentre la transazione è attiva: nel task che l’ha creata o in un gestore success o error di una delle sue richieste. Dopo await fetch(...) potrebbe essere già stata confermata automaticamente; una richiesta successiva può generare TransactionInactiveError. Il successo di una singola richiesta non equivale al successo della transazione. complete conferma il commit; abort indica che le modifiche sono state annullate.

IndexedDB è un’API Web, non una funzionalità di ECMAScript 2024. L’accesso è limitato alla stessa origine; le impostazioni del browser possono limitare l’accesso allo spazio di archiviazione o la durata di conservazione dei dati.

Esempi

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IndexedDB example</title>
</head>
<body>
<script>
(async () => {
  const idb = window.indexedDB;
  const name = `cktis-notes-${crypto.randomUUID()}`;
  const requestResult = (request) => new Promise((resolve, reject) => {
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
  const finished = (tx) => new Promise((resolve, reject) => {
    tx.oncomplete = () => resolve();
    tx.onabort = () => reject(tx.error ?? new Error("Transaction aborted"));
  });

  const open = idb.open(name, 1);
  open.onupgradeneeded = () => {
    open.result.createObjectStore("notes", { keyPath: "id" });
  };
  const db = await requestResult(open);
  db.onversionchange = () => db.close();

  let title;
  try {
    const write = db.transaction("notes", "readwrite");
    write.objectStore("notes").put({ id: 1, title: "IndexedDB" });
    await finished(write);

    const read = db.transaction("notes");
    const get = read.objectStore("notes").get(1);
    await finished(read);
    title = get.result.title;
  } finally {
    db.close();
    await requestResult(idb.deleteDatabase(name));
  }
  console.log(title);
})().catch((error) => console.error(error));
</script>
</body>
</html>

Risultato

IndexedDB

Servi il file HTML tramite HTTPS e aprilo in un browser in cui l’archiviazione è consentita. L’esempio crea un database con un nome casuale, legge il record dopo il commit della scrittura, chiude ed elimina il database, quindi stampa `IndexedDB` nella console del browser.

Lezioni correlate

  • JavaScript · Lezione 31 · Avanzato · Versione: 4

Fonti