CKTIS / JavaScript
Отваряне на IndexedDB: upgradeneeded, blocked, success и error
Разпознай кога заявка за отваряне на IndexedDB изисква промяна на схемата, изчаква затваряне на връзка, успява или завършва с грешка.
Версия: ECMAScript 2024 and the current web platform; runtime support varies
Синтаксис
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) веднага връща IDBOpenDBRequest, а не Promise. Отварянето е асинхронно. upgradeneeded и blocked са събития на IDBOpenDBRequest, а success и error се наследяват от IDBRequest. Без version се отваря съществуващата версия или се създава база с версия 1. IndexedDB е API на уеб платформата, а не част от ECMAScript; достъпът зависи от средата за изпълнение и настройките за съхранение.
upgradeneeded възниква при създаване на база (oldVersion === 0) или заявка за по-висока версия. Използвай oldVersion и newVersion от събитието, за да определиш нужните миграции. Променяй схемата чрез request.result в активната транзакция versionchange, достъпна в request.transaction. Не разчитай, че тя ще остане активна, докато изчакваш несвързана операция като fetch().
blocked означава, че заявката за надграждане чака друга връзка към същата база да се затвори. Ако връзката вече чака да бъде затворена, IndexedDB не ѝ изпраща versionchange, но тя все пак може да забави надграждането, докато транзакциите ѝ приключат. В приложението обработи versionchange върху съществуващата връзка IDBDatabase и извикай close() за нея. Използвай blocked, за да обясниш на потребителя причината за изчакването. Не е нужно да повтаряш заявката.
success означава, че request.result съдържа отворената връзка IDBDatabase. Ако е била нужна миграция, транзакцията ѝ вече е потвърдена. Отварянето на текущата версия не предизвиква upgradeneeded. Успешното отваряне не гарантира успеха на следващите транзакции.
error означава, че заявката е неуспешна. Прочети DOMException от request.error. Заявка за версия, по-ниска от записаната, води до VersionError; прекъсването на транзакцията за миграция отменя промените ѝ и отварянето се проваля. Синхронна грешка като TypeError за версия 0 се хвърля директно от open(), без събитие error.
Примери
<!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>Резултат
upgradeneeded: 0 -> 1 success: 1 blocked: 2 upgradeneeded: 1 -> 2 success: 2 error: VersionError
Отвори HTML страницата през HTTPS или от localhost в браузър, в който са достъпни IndexedDB и `crypto.randomUUID()`. Връзката към версия `1` умишлено остава отворена до `blocked`. След затварянето ѝ същата заявка отваря версия `2`. Следващата заявка за версия `1` завършва с `VersionError`.
Свързани уроци
- JavaScript · Урок 20 · Средно · Версия: 3
- JavaScript · Урок 21 · Средно · Версия: 3
Източници
- 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