CKTIS / JavaScript
Otevírání IndexedDB: upgradeneeded, blocked, success a error
Rozpoznej, kdy požadavek na otevření IndexedDB vyžaduje změnu schématu, čeká na uzavření připojení, uspěl nebo selhal.
Verze: ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
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) okamžitě vrací IDBOpenDBRequest, nikoli Promise. Otevírání probíhá asynchronně. upgradeneeded a blocked patří k IDBOpenDBRequest; success a error jsou zděděné z IDBRequest. Bez version se otevře stávající verze nebo se vytvoří databáze ve verzi 1. IndexedDB je API webové platformy, nikoli součást ECMAScriptu; přístup závisí na prostředí a nastavení úložiště.
upgradeneeded nastane při vytvoření databáze (oldVersion === 0) nebo při požadavku na vyšší verzi. Podle oldVersion a newVersion z události urči potřebné migrace. Schéma měň přes request.result v aktivní transakci versionchange dostupné v request.transaction. Nespoléhej na to, že transakce zůstane aktivní při čekání na nesouvisející operaci, například fetch().
blocked znamená, že požadavek na zvýšení verze čeká na uzavření jiného připojení ke stejné databázi. Pokud už připojení čeká na uzavření, IndexedDB mu událost versionchange nepošle, ale jeho probíhající transakce mohou zvýšení verze zdržet, dokud neskončí. V aplikaci obsluž versionchange na stávajícím připojení IDBDatabase a zavolej na něm close(). Pomocí blocked vysvětli uživateli důvod čekání. Požadavek není třeba opakovat.
success znamená, že request.result obsahuje otevřené připojení IDBDatabase. Pokud byla potřeba migrace, její transakce už byla potvrzena. Otevření aktuální verze nevyvolá upgradeneeded. Úspěšné otevření nezaručuje úspěch pozdějších transakcí.
error znamená, že požadavek selhal. Přečti DOMException z request.error. Požadavek na nižší než uloženou verzi způsobí VersionError; zrušení transakce migrace vrátí její změny zpět a otevření selže. Synchronní chybu, například TypeError pro verzi 0, vyvolá přímo open(), nikoli událost error.
Příklady
<!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>Výsledek
upgradeneeded: 0 -> 1 success: 1 blocked: 2 upgradeneeded: 1 -> 2 success: 2 error: VersionError
Otevři stránku HTML přes HTTPS nebo z localhostu v prohlížeči, ve kterém jsou dostupné IndexedDB a `crypto.randomUUID()`. Připojení k verzi `1` zůstává záměrně otevřené až do události `blocked`. Po jeho uzavření stejný požadavek otevře verzi `2`. Další požadavek na verzi `1` selže s `VersionError`.
Související lekce
- JavaScript · Lekce 20 · Středně pokročilá · Verze: 3
- JavaScript · Lekce 21 · Středně pokročilá · Verze: 3
Zdroje
- 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