CKTIS / JavaScript
Otvaranje IndexedDB-a: upgradeneeded, blocked, success i error
Razlikuj kada zahtjev za otvaranje IndexedDB-a traži nadogradnju sheme, čeka zatvaranje veze, uspijeva ili završava pogreškom.
Verzija: ECMAScript 2024 and the current web platform; runtime support varies
Sintaksa
const request = indexedDB.open(name); // or indexedDB.open(name, version)
request.addEventListener("upgradeneeded", onUpgradeNeeded);
request.addEventListener("blocked", onBlocked);
request.addEventListener("success", onSuccess);
request.addEventListener("error", onError);
// Alternatively, assign one handler to each property:
request.onupgradeneeded = onUpgradeNeeded;
request.onblocked = onBlocked;
request.onsuccess = onSuccess;
request.onerror = onError;indexedDB.open(name, version) odmah vraća IDBOpenDBRequest, a ne Promise. Otvaranje se odvija asinkrono. upgradeneeded i blocked pripadaju sučelju IDBOpenDBRequest; success i error naslijeđeni su iz IDBRequest. Ako izostaviš version, otvara se postojeća verzija ili se stvara baza u verziji 1. IndexedDB je API web-platforme, ne dio ECMAScripta; pristup ovisi o izvršnom okruženju i postavkama pohrane.
upgradeneeded okida se pri stvaranju baze (oldVersion === 0) ili kada zatražiš višu verziju. Pomoću oldVersion i newVersion iz događaja odredi potrebne migracije. Mijenjaj shemu preko request.result unutar aktivne transakcije versionchange dostupne u request.transaction. Nemoj računati na to da će ostati aktivna dok čekaš nepovezanu operaciju kao što je fetch().
blocked znači da zahtjev za nadogradnju čeka da se zatvori druga veza s istom bazom. Ako veza već čeka zatvaranje, IndexedDB joj ne šalje događaj versionchange, ali ona ipak može odgoditi nadogradnju dok se njezine transakcije ne dovrše. U aplikaciji obradi versionchange na postojećoj vezi IDBDatabase i na njoj pozovi close(). Događajem blocked objasni korisniku zašto se čeka. Zahtjev ne treba ponavljati.
success znači da request.result sadrži otvorenu vezu IDBDatabase. Ako je bila potrebna nadogradnja, njezina je transakcija već potvrđena. Otvaranje trenutačne verzije ne okida upgradeneeded. Uspješno otvaranje ne jamči uspjeh kasnijih transakcija.
error znači da zahtjev nije uspio. Pročitaj DOMException iz request.error. Zahtjev za verziju nižu od pohranjene daje VersionError; prekid transakcije nadogradnje poništava njezine promjene i uzrokuje neuspjeh otvaranja. Sinkronu pogrešku, primjerice TypeError za verziju 0, izravno baca open(), bez događaja error.
Primjeri
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB open request events</title>
</head>
<body>
<pre id="output"></pre>
<script>
(async () => {
const { indexedDB, crypto } = window;
const output = document.getElementById("output");
const name = `ck-tis-idb-${crypto.randomUUID()}`;
function log(line) {
output.textContent += (output.textContent ? "\n" : "") + line;
console.log(line);
}
function open(version, releaseBlocker) {
return new Promise((resolve, reject) => {
const request = indexedDB.open(name, version);
request.onupgradeneeded = ({ oldVersion, newVersion }) => {
log(`upgradeneeded: ${oldVersion} -> ${newVersion}`);
const db = request.result;
if (oldVersion < 1) db.createObjectStore("notes");
if (oldVersion < 2 && newVersion >= 2) db.createObjectStore("tags");
};
request.onblocked = () => {
log(`blocked: ${version}`);
releaseBlocker?.();
};
request.onsuccess = () => {
log(`success: ${request.result.version}`);
resolve(request.result);
};
request.onerror = () => reject(request.error);
});
}
let first;
let second;
try {
first = await open(1);
// Intentionally keep version 1 open until the next request is blocked.
second = await open(2, () => first.close());
try {
const unexpected = await open(1);
unexpected.close();
throw new Error("Expected VersionError");
} catch (error) {
if (error.name !== "VersionError") throw error;
log(`error: ${error.name}`);
}
} finally {
first?.close();
second?.close();
const cleanup = indexedDB.deleteDatabase(name);
cleanup.onerror = () => console.error(cleanup.error);
}
})().catch((error) => console.error(error));
</script>
</body>
</html>Rezultat
upgradeneeded: 0 -> 1 success: 1 blocked: 2 upgradeneeded: 1 -> 2 success: 2 error: VersionError
Otvori HTML stranicu preko HTTPS-a ili s adrese localhost u pregledniku u kojem su dostupni IndexedDB i `crypto.randomUUID()`. Veza s verzijom `1` namjerno ostaje otvorena do događaja `blocked`. Nakon zatvaranja veze isti zahtjev otvara verziju `2`. Sljedeći zahtjev za verziju `1` ne uspijeva zbog `VersionError`.
Povezane lekcije
- JavaScript · Lekcija 20 · Srednje · Verzija: 3
- JavaScript · Lekcija 21 · Srednje · Verzija: 3
Izvori
- IDBOpenDBRequest
- IDBFactory: open() method
- IDBOpenDBRequest: upgradeneeded event
- IDBOpenDBRequest: blocked event
- IDBRequest: success event
- IDBRequest: error event
- IDBRequest: error property
- IDBRequest: transaction property
- IDBVersionChangeEvent
- IDBDatabase: versionchange event
- Using IndexedDB
- Crypto: randomUUID() method