Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

IndexedDB: onupgradeneeded i transakcja zmiany wersji

Zmień schemat IndexedDB w `onupgradeneeded`, odczytaj transakcję z `request.transaction` i zacznij korzystać z nowego schematu po `success`.

Wersja: Current web platform; runtime support varies

Składnia

// The upgrade lifecycle is defined by IndexedDB, not by an ECMAScript edition.
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => {
  const db = request.result;
  const tx = request.transaction;
  // Apply schema changes through db and tx while tx is active.
};

indexedDB.open(name, version) natychmiast zwraca IDBOpenDBRequest; samo otwarcie odbywa się asynchronicznie. onupgradeneeded to właściwość obsługi zdarzenia upgradeneeded. Zdarzenie jest wywoływane przy tworzeniu bazy albo otwieraniu jej z wyższą wersją. Przy tej samej wersji go nie ma, a żądanie niższej wersji kończy się błędem VersionError. IndexedDB jest API platformy webowej, a nie funkcją ECMAScript 2024.

W funkcji obsługi request.result to połączenie IDBDatabase, a request.transaction to odziedziczona z IDBRequest właściwość tylko do odczytu. Zawiera transakcję IDBTransaction w trybie "versionchange", tworzoną automatycznie przez IndexedDB. Bezpośrednio po open() i ponownie w success właściwość ta ma wartość null. db.transaction() tworzy osobną transakcję w trybie "readonly" lub "readwrite", a nie transakcję zmiany wersji.

Użyj event.oldVersion i event.newVersion, by wybrać odpowiednie kroki migracji. Dla nowej bazy oldVersion wynosi 0; kolejne, niezależne warunki pozwalają wykonać kilka kroków przy pominięciu wersji pośrednich. Utwórz magazyn przez db.createObjectStore(), a do istniejącego magazynu dodaj indeks przez tx.objectStore(name).createIndex(). W tej samej transakcji możesz też migrować dane.

Zlecaj operacje, gdy transakcja jest aktywna: bezpośrednio w funkcji obsługi upgradeneeded lub w funkcjach obsługi zdarzeń jej żądań. Nie zakładaj, że transakcja będzie nadal aktywna po await fetch() lub po upływie czasu odmierzanego przez timer. tx.abort() wycofuje zmiany schematu, danych i wersji, a żądanie otwarcia kończy się zdarzeniem error zamiast success. Jeśli transakcja zatwierdzi zmiany, najpierw wystąpi jej complete, a potem success żądania otwarcia.

Otwarte połączenie, na przykład w innej karcie, może wstrzymać zmianę wersji. Obsłuż blocked na żądaniu otwarcia, a w funkcji obsługi versionchange istniejącego połączenia zamknij je przez db.close().

Przykłady

<!doctype html>
<meta charset="utf-8">
<title>IndexedDB upgrade transaction</title>
<script>
(() => {
  const name = `cktis-indexeddb-${crypto.randomUUID()}`;
  const reportError = (event) => console.error(event.target.error);

  function openVersion(version) {
    const request = indexedDB.open(name, version);
    request.onerror = reportError;
    request.onupgradeneeded = ({ oldVersion, newVersion }) => {
      const db = request.result;
      const tx = request.transaction;
      if (oldVersion < 1) db.createObjectStore("books", { keyPath: "id" });
      if (oldVersion < 2 && newVersion >= 2) {
        console.log(`upgrade: ${oldVersion} -> ${newVersion} (${tx.mode})`);
        tx.objectStore("books").createIndex("by_title", "title");
        tx.oncomplete = () => console.log("complete");
      }
    };
    return request;
  }

  const first = openVersion(1);
  first.onsuccess = () => {
    first.result.close();
    const second = openVersion(2);
    console.log(`before: ${second.transaction}`);
    second.onsuccess = () => {
      const db = second.result;
      const store = db.transaction("books", "readonly").objectStore("books");
      console.log(`success: ${second.transaction}; index: ${store.indexNames.contains("by_title")}`);
      db.close();
      indexedDB.deleteDatabase(name).onerror = reportError;
    };
  };
})();
</script>

Wynik

before: null
upgrade: 1 -> 2 (versionchange)
complete
success: null; index: true

Otwórz stronę HTML w przeglądarce w bezpiecznym kontekście, z dostępem do IndexedDB i `crypto.randomUUID()`. Wynik zobaczysz w konsoli deweloperskiej. Przykład tworzy bazę o losowej nazwie w wersji 1, zamyka połączenie, dodaje `by_title` w wersji 2 i po sprawdzeniu indeksu zleca usunięcie bazy testowej.

Powiązane lekcje

  • JavaScript · Lekcja 31 · Zaawansowany · Wersja: 4

Źródła