IDBRequest

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2021.

IDBRequest は IndexedDB API のインターフェイスで、データベースやデータベースオブジェクトへの非同期の要求の結果へのアクセスをイベントハンドラープロパティによって提供します。データベースの読み書きは、それぞれ要求を用いて行います。

要求オブジェクトは、最初は操作の結果の情報を何も持っていません。情報が得られるようになると、要求でイベントが発生し、IDBRequest のインスタンスのプロパティを通じて情報が得られるようになります。

全ての非同期操作は、すぐに IDBRequest のインスタンスを返します。それぞれの要求は 'pending' 状態に設定された readyState を持ちます。要求が完了するか失敗すると、これは 'done' に変わります。状態が done に設定されると、それぞれの要求は result と error を返し、要求でイベントが発生します。状態が pending のままである間は、result や error にアクセスしようとすると InvalidStateError 例外が発生します。

平たく言えば、全ての非同期メソッドは要求オブジェクトを返します。要求が正常に完了すると、結果が result プロパティを通じて取得できるようになり、成功を表すイベント (IDBRequest.onsuccess) が発生します。操作の実行中にエラーが発生すると、例外が error プロパティを通じて取得できるようになり、エラーイベント (IDBRequest.onerror) が発生します。

IDBOpenDBRequest インターフェイスは IDBRequest から派生しています。

メモ: この機能はウェブワーカー内で利用可能です。

EventTarget IDBRequest

インスタンスプロパティ

EventTarget からもプロパティを継承しています。

IDBRequest.error 読取専用

要求が失敗したとき DOMException を返し、何が失敗したのかを示します。

IDBRequest.result 読取専用

要求の結果を返します。要求が完了していない場合は結果は参照できず、InvalidStateError 例外が投げられます。

IDBRequest.source 読取専用

IDBIndex や IDBObjectStore などの要求元です。(IDBFactory.open を呼んだときなど) 要求元が存在しない場合は null を返します。

IDBRequest.readyState 読取専用

要求の状態です。全ての要求は開始時 pending 状態です。要求が正常に完了するか、エラーが発生すると、状態は done に変わります。

IDBRequest.transaction 読取専用

要求用のトランザクションです。例えばアップグレードが不要な場合に IDBFactory.open から返される要求など、このプロパティが null になる要求もあります。(データベースに接続するだけなので、返すべきトランザクションがありません)

インスタンスメソッド

メソッドはありませんが、メソッドを EventTarget から継承しています。

イベント

addEventListener() を用いるか、このインターフェイスの oneventname プロパティにイベントリスナーを代入することで、これらのイベントをリッスンします。

error

エラーにより要求が失敗した場合に発生します。 onerror プロパティ経由でも利用可能です。

success

IDBRequest が成功した場合に発生します。 onsuccess プロパティ経由でも利用可能です。

例

以下のコードスニペットでは、データベースを非同期で開いて要求を作成します。onerror および onsuccess 関数が、成功と失敗のケースを扱うために入っています。動く例全体は､To-do Notifications アプリケーション (動く例を見る) を見てください｡

js
var db;

// 我々のデータベースを開きましょう
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

// これら 2 個のイベントハンドラーは､データベースが正常に開かれたか､
// 失敗した時に動作します｡
DBOpenRequest.onerror = function (event) {
  note.innerHTML += "<li>データベースの読み込みに失敗しました。</li>";
};

DBOpenRequest.onsuccess = function (event) {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を保存します｡
  db = DBOpenRequest.result;
};

仕様書

Specification
Indexed Database API 3.0
# request-api

ブラウザーの互換性

BCD tables only load in the browser

関連情報