База знанияИзпитен център
BGБългарски
Избери език13

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

Източници