Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

Otwieranie IndexedDB: upgradeneeded, blocked, success i error

Rozpoznaj, kiedy żądanie otwarcia IndexedDB aktualizuje schemat, czeka na zamknięcie połączenia, kończy się powodzeniem lub zgłasza błąd.

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

Składnia

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) natychmiast zwraca IDBOpenDBRequest, a nie Promise. Otwarcie odbywa się asynchronicznie. upgradeneeded i blocked należą do IDBOpenDBRequest, a success i error są dziedziczone z IDBRequest. Bez version żądanie otwiera istniejącą wersję albo tworzy bazę w wersji 1. IndexedDB to API platformy WWW, nie część ECMAScript; dostęp zależy od środowiska i ustawień przechowywania danych.

blocked oznacza, że żądanie aktualizacji nadal czeka na zamknięcie innego połączenia z tą samą bazą. Jeśli połączenie już czeka na zamknięcie, IndexedDB pomija je przy wysyłaniu versionchange, ale może ono nadal wstrzymywać aktualizację do zakończenia swoich transakcji. W aplikacji obsłuż versionchange na istniejącym połączeniu IDBDatabase i wywołaj na nim close(). W obsłudze blocked poinformuj użytkownika o oczekiwaniu. Nie trzeba ponawiać żądania.

success oznacza, że request.result zawiera otwarte połączenie IDBDatabase. Jeśli była potrzebna migracja, jej transakcja została już zatwierdzona. Otwarcie bieżącej wersji nie wywołuje upgradeneeded. Sukces otwarcia nie gwarantuje powodzenia późniejszych transakcji.

error oznacza, że żądanie się nie powiodło. Odczytaj DOMException z request.error. Żądanie wersji niższej niż zapisana daje VersionError; przerwanie transakcji migracji cofa jej zmiany i powoduje niepowodzenie otwarcia. Błąd synchroniczny, np. TypeError dla wersji 0, jest wyjątkiem zgłaszanym przez samo open(), a nie zdarzeniem error.

Przykłady

<!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>

Wynik

upgradeneeded: 0 -> 1
success: 1
blocked: 2
upgradeneeded: 1 -> 2
success: 2
error: VersionError

Otwórz stronę HTML przez HTTPS lub na localhost w przeglądarce z dostępnym IndexedDB i `crypto.randomUUID()`. Przykład celowo pozostawia połączenie z wersją `1` otwarte aż do `blocked`. Po jego zamknięciu to samo żądanie otwiera wersję `2`. Kolejne żądanie wersji `1` kończy się `VersionError`.

Powiązane lekcje

  • JavaScript · Lekcja 20 · Średniozaawansowany · Wersja: 3
  • JavaScript · Lekcja 21 · Średniozaawansowany · Wersja: 3

Źródła