IDBRequest
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.error
読取専用-
要求が失敗したとき
DOMException
を返し、何が失敗したのかを示します。 IDBRequest.result
読取専用-
要求の結果を返します。要求が完了していない場合は結果は参照できず、
InvalidStateError
例外が投げられます。 IDBRequest.source
読取専用-
IDBIndex
やIDBObjectStore
などの要求元です。(IDBFactory.open
を呼んだときなど) 要求元が存在しない場合はnull
を返します。 IDBRequest.readyState
読取専用-
要求の状態です。全ての要求は開始時
pending
状態です。要求が正常に完了するか、エラーが発生すると、状態はdone
に変わります。 IDBRequest.transaction
読取専用-
要求用のトランザクションです。例えばアップグレードが不要な場合に
IDBFactory.open
から返される要求など、このプロパティがnull
になる要求もあります。(データベースに接続するだけなので、返すべきトランザクションがありません)
インスタンスメソッド
メソッドはありませんが、メソッドを EventTarget
から継承しています。
イベント
例
以下のコードスニペットでは、データベースを非同期で開いて要求を作成します。onerror
および onsuccess
関数が、成功と失敗のケースを扱うために入っています。動く例全体は、To-do Notifications アプリケーション (動く例を見る) を見てください。
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
関連情報
- IndexedDB の使用
- トランザクションの開始 :
IDBDatabase
- トランザクションの使用 :
IDBTransaction
- キーの範囲の設定 :
IDBKeyRange
- データの取得と変更 :
IDBObjectStore
- カーソルの使用 :
IDBCursor
- リファレンス例 : To-do Notifications (動く例を見る)