CKTIS / JavaScript
IDBRequest: wynik, błąd i procedury obsługi zdarzeń
Odczytuj `result` po powodzeniu żądania IndexedDB, a `error` po jego niepowodzeniu. Powodzenie pojedynczego żądania nie oznacza zatwierdzenia transakcji.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
// 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);IDBRequest to obiekt żądania IndexedDB, a nie obietnica (Promise). IndexedDB jest interfejsem platformy WWW, a nie częścią ECMAScript 2024; jego dostępność zależy od środowiska wykonawczego. Gdy readyState ma wartość "pending", odczyt dowolnej z właściwości tylko do odczytu, result lub error, zgłasza wyjątek DOMException o nazwie InvalidStateError. Stan "done" pozwala odczytać te właściwości, ale nie oznacza powodzenia. Żądanie IDBOpenDBRequest może mieć stan "done" podczas zdarzenia upgradeneeded, zanim wystąpi końcowe zdarzenie success lub error.
Przypisz funkcje do request.onsuccess i request.onerror, aby obsłużyć odpowiednio zdarzenia success i error. Ponowne przypisanie zastępuje poprzednią funkcję; addEventListener() pozwala dodać osobne funkcje nasłuchujące, używając nazw zdarzeń bez przedrostka on. Po powodzeniu odczytaj request.result, którego wartość zależy od operacji: add() zwraca klucz przez result, a get() może zakończyć się pomyślnie z wynikiem undefined, gdy klucza nie ma. Przy powodzeniu request.error ma wartość null; przy niepowodzeniu zawiera DOMException, a request.result ma wartość undefined. Błąd asynchroniczny nie trafi do catch otaczającego wywołanie, choć samo wywołanie może zgłosić wyjątek synchronicznie.
Zdarzenie success nie propaguje się w górę i nie można go anulować. W przypadku żądania należącego do transakcji zdarzenie error propaguje się w górę i domyślnie powoduje przerwanie transakcji. Wywołaj event.preventDefault() w obsłudze przewidywanego błędu, po którym można kontynuować, aby zapobiec temu domyślnemu przerwaniu. Nie zmienia to wyniku żądania ani nie zatrzymuje propagacji zdarzenia.
Powodzenie pojedynczego zapisu nie oznacza zatwierdzenia transakcji. Dalsze żądania składaj, gdy transakcja jest aktywna, na przykład bezpośrednio w procedurze obsługi zdarzenia żądania. Na poziomie transakcji nasłuchuj complete, aby wykryć zatwierdzenie, oraz abort, aby wykryć wycofanie zmian.
Przykłady
<!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>Wynik
success: 1 error: ConstraintError transaction: complete
Zapisz przykład jako plik HTML i udostępnij go przez HTTPS. Otwórz stronę w przeglądarce, w której działają IndexedDB i `crypto.randomUUID()`, i sprawdź komunikaty w konsoli. Pierwsze `add()` zwraca klucz `1` przez `result`, drugie kończy się błędem `ConstraintError`, a `preventDefault()` zapobiega przerwaniu z tego powodu, więc transakcja może się zakończyć zdarzeniem `complete`. Po zakończeniu transakcji kod zamyka połączenie i zleca usunięcie bazy utworzonej dla tego uruchomienia.
Powiązane lekcje
- JavaScript · Lekcja 31 · Zaawansowany · Wersja: 4