CKTIS / JavaScript
IndexedDB-Transaktionsereignisse: complete, abort und error
Mit `complete` und `abort` erkennst du das Ergebnis der gesamten IndexedDB-Transaktion; mit `error` untersuchst du eine fehlgeschlagene Anfrage.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
tx.addEventListener("complete", onComplete);
tx.addEventListener("abort", onAbort);
tx.addEventListener("error", onRequestError);
// Property-based alternatives:
tx.oncomplete = onComplete;
tx.onabort = onAbort;
tx.onerror = onRequestError;
// Read the transaction's error, if any:
const failure = tx.error;
// To explicitly roll back a transaction that can still be aborted:
tx.abort();Registriere Listener für complete, abort und error auf der Transaktion tx mit addEventListener() oder über oncomplete, onabort und onerror. complete bedeutet, dass die gesamte Transaktion erfolgreich abgeschlossen wurde. Das success-Ereignis einer einzelnen Anfrage reicht dafür nicht aus: Ein späterer Fehler kann auch deren Änderungen rückgängig machen. Ein erfolgreicher Commit bedeutet je nach Durabilitätseinstellung und Laufzeitumgebung nicht zwingend, dass die Daten bereits auf den Datenträger geschrieben wurden.
abort bedeutet, dass die Transaktion ohne Commit beendet und ihre Änderungen rückgängig gemacht wurden. Das Ereignis steigt bis zum IDBDatabase-Objekt auf und ist nicht abbrechbar. Es kann nach einem expliziten Aufruf von tx.abort() oder nach einem Fehler eintreten. Lies im abort-Handler tx.error: Diese schreibgeschützte Eigenschaft enthält eine DOMException mit der Fehlerursache oder null, etwa nach einem expliziten tx.abort().
Ein error-Ereignis entsteht an einem IDBRequest und steigt über tx zur Datenbank auf. Die Ursache steht in event.target.error, nicht in tx.error, das noch null sein kann. Standardmäßig bricht ein Anfragefehler die Transaktion ab. Rufe bei einem erwarteten Fehler im Handler event.preventDefault() auf, um genau diesen Abbruch zu verhindern; stopPropagation() allein reicht nicht. Die Anfrage bleibt fehlgeschlagen. Das endgültige Ergebnis der Transaktion zeigen complete oder abort.
IndexedDB ist eine API der Webplattform und kein Teil von ECMAScript 2024. Stelle Anfragen, solange die Transaktion aktiv ist, etwa direkt nach der Erstellung oder in ihren Anfrage-Handlern. Nach dem Warten auf einen unabhängigen Vorgang wie fetch() nimmt die Transaktion möglicherweise keine Anfragen mehr an. Die Verfügbarkeit hängt von der Laufzeitumgebung und den Speicherregeln ab.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB transaction events</title>
</head>
<body>
<pre id="output"></pre>
<script>
void (async () => {
const output = document.getElementById("output");
function log(line) {
console.log(line);
output.textContent += `${line}\n`;
}
const name = `cktis-tx-${Date.now()}-${Math.random().toString(36).slice(2)}`;
const indexedDB = window.indexedDB;
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => open.result.createObjectStore("items");
const db = await new Promise((resolve, reject) => {
open.onsuccess = () => resolve(open.result);
open.onerror = () => reject(open.error);
});
function write(label, cancelError) {
return new Promise((resolve) => {
const tx = db.transaction("items", "readwrite");
tx.oncomplete = () => resolve("complete");
tx.onabort = () => resolve(`abort: ${tx.error?.name ?? "no error"}`);
tx.onerror = (event) => {
log(`${label} error: ${event.target.error.name}`);
};
const items = tx.objectStore("items");
items.add("first", label);
const duplicate = items.add("second", label);
if (cancelError) {
duplicate.onerror = (event) => {
if (duplicate.error.name === "ConstraintError") event.preventDefault();
};
}
});
}
try {
for (const [label, cancelError] of [["rollback", false], ["recover", true]]) {
log(`${label} ${await write(label, cancelError)}`);
}
const values = await new Promise((resolve, reject) => {
const tx = db.transaction("items", "readonly");
const items = tx.objectStore("items");
const rolledBack = items.get("rollback");
const recovered = items.get("recover");
tx.oncomplete = () => resolve([rolledBack.result, recovered.result]);
tx.onabort = () => reject(tx.error ?? new Error("Read aborted"));
});
log(`stored: ${values.map(String).join(",")}`);
} finally {
db.close();
await new Promise((resolve, reject) => {
const deletion = indexedDB.deleteDatabase(name);
deletion.onsuccess = () => resolve();
deletion.onerror = () => reject(deletion.error);
});
}
})().catch(console.error);
</script>
</body>
</html>Ergebnis
rollback error: ConstraintError rollback abort: ConstraintError recover error: ConstraintError recover complete stored: undefined,first
Stelle das Beispiel als HTML-Seite über HTTPS bereit und öffne sie in einem Browser, in dem IndexedDB verfügbar und das Speichern von Daten erlaubt ist. Beide Transaktionen melden wegen eines doppelten Schlüssels `ConstraintError`. Die erste macht den ersten Schreibvorgang rückgängig; die zweite übernimmt ihn, weil der Fehler-Handler die Standardaktion verhindert.
Zugehörige Lektionen
- JavaScript · Lektion 20 · Mittlere Stufe · Version: 3
- JavaScript · Lektion 21 · Mittlere Stufe · Version: 3