CKTIS / JavaScript
IDBRequest: Ergebnis, Fehler und Ereignishandler
Lies nach einer erfolgreichen IndexedDB-Anfrage `result` und nach einem Fehlschlag `error`. Eine erfolgreiche Anfrage bedeutet noch nicht, dass die Transaktion festgeschrieben wurde.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
// Read-only members; do not read either while readyState is "pending".
// request.result
// request.error
request.onsuccess = (event) => { /* read request.result */ };
request.onerror = (event) => { /* read request.error */ };
// Alternative registration; event names omit the "on" prefix.
request.addEventListener("success", handleSuccess);
request.addEventListener("error", handleError);Ein IDBRequest ist ein Anfrageobjekt von IndexedDB, kein Promise. IndexedDB ist eine Web-API und kein Bestandteil von ECMAScript 2024; die Verfügbarkeit hängt von der Laufzeitumgebung ab. Solange readyState den Wert "pending" hat, löst das Lesen der schreibgeschützten Eigenschaften result oder error eine DOMException namens InvalidStateError aus. Bei "done" lassen sich diese Eigenschaften lesen, doch der Zustand zeigt keinen Erfolg an. Ein IDBOpenDBRequest kann bereits während upgradeneeded den Zustand "done" melden, bevor das abschließende Ereignis success oder error eintritt.
Weise request.onsuccess und request.onerror Funktionen zu, um success bzw. error zu behandeln. Eine erneute Zuweisung ersetzt den bisherigen Handler; mit addEventListener() kannst du unter dem Ereignisnamen ohne on separate Listener hinzufügen. Bei Erfolg liest du request.result: Der Wert hängt von der Operation ab. So liefert add() den Schlüssel über result, während get() bei fehlendem Schlüssel mit undefined erfolgreich sein kann. Bei Erfolg ist request.error gleich null; bei einem Fehlschlag enthält es eine DOMException, und request.result ist undefined. try...catch um den Aufruf fängt synchrone Ausnahmen des Aufrufs ab, nicht aber spätere Anfragefehler.
Das Ereignis success steigt nicht zu übergeordneten Objekten auf und ist nicht abbrechbar. Bei einer Anfrage innerhalb einer Transaktion steigt error auf und bricht die Transaktion standardmäßig ab. Bei einem erwarteten, behebbaren Fehler verhindert event.preventDefault() im Handler diesen standardmäßigen Abbruch. Die Anfrage bleibt fehlgeschlagen, und das Ereignis steigt weiterhin auf.
Eine erfolgreiche Schreibanfrage bedeutet nicht, dass die Transaktion festgeschrieben wurde. Stelle weitere Anfragen, solange die Transaktion aktiv ist, etwa direkt im Ereignishandler einer Anfrage. Überwache an der Transaktion complete für die Festschreibung und abort für das Zurückrollen.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IDBRequest: success and error</title>
</head>
<body>
<p>Open the browser developer console to see the output.</p>
<script>
(() => {
const name = `cktis-idbrequest-${window.crypto.randomUUID()}`;
const open = window.indexedDB.open(name, 1);
open.onupgradeneeded = () => open.result.createObjectStore("items");
open.onerror = () => console.error("open:", open.error.name);
open.onsuccess = () => {
const db = open.result;
const tx = db.transaction("items", "readwrite");
const store = tx.objectStore("items");
function cleanup() {
db.close();
const deletion = window.indexedDB.deleteDatabase(name);
deletion.onerror = () => console.error("cleanup:", deletion.error.name);
}
tx.oncomplete = () => {
console.log("transaction: complete");
cleanup();
};
tx.onabort = () => {
console.error("transaction: aborted", tx.error?.name);
cleanup();
};
const first = store.add("first", 1);
first.onsuccess = () => console.log(`success: ${first.result}`);
const duplicate = store.add("second", 1);
duplicate.onerror = (event) => {
const { name } = duplicate.error;
if (name === "ConstraintError") event.preventDefault();
console.log(`error: ${name}`);
};
};
})();
</script>
</body>
</html>Ergebnis
success: 1 error: ConstraintError transaction: complete
Speichere das Beispiel als HTML-Datei und stelle sie über HTTPS bereit. Öffne die Seite in einem Browser, in dem IndexedDB und `crypto.randomUUID()` verfügbar sind, und prüfe die Ausgabe in der Entwicklerkonsole. Das erste `add()` liefert den Schlüssel `1` über `result`; das zweite scheitert mit `ConstraintError`. `preventDefault()` verhindert den Abbruch aufgrund dieses Fehlers, sodass die Transaktion `complete` auslösen kann. Nach Transaktionsende schließt der Code die Verbindung und veranlasst das Löschen der für diesen Durchlauf angelegten Datenbank.
Zugehörige Lektionen
- JavaScript · Lektion 31 · Fortgeschritten · Version: 4