IDBRequest
IndexedDB api 中的 IDBRequest 接口提供了根据绑定事件处理函数访问结果集的方法。其中结果集来自对数据库和数据库对象发起的异步查询。对数据库的读写操作都是通过 request 的方式来实现。
该 request 对象初始时不包括任何关于操作结果的信息,当 request 上的事件触发时,可以通过 IDBRequest 实例上的事件处理函数访问相关信息。
继承自:EventTarget
About this document
This document was last updated on August 17, 2012 and follows the W3C Specifications (Editor's Draft) drafted on July 24, 2012. It has not yet been verified.
基础概念
所有异步操作立即返回一个 IDBRequest 实例。每一个请求都有一个 readyState 属性,初始时为 pending,当请求完成或失败的时候,readyState 会变为 done。当状态值变为 done 时,每一个请求都会返回 result 和 error 属性,并且会触发一个事件。当状态保持为 pending 时,任何尝试访问 result 或 error 属性的行为会触发一个 InvalidStateError 异常。
用直白的话来说就是:所有的异步方法返回一个 request 对象。如果 request 对象成功执行了,结果可以通过 result 属性访问到,并且该 request 对象上会触发 success 事件。如果操作中有错误发生,一个 error 事件会触发,并且会通过 result 属性抛出一个异常。
示例
下面的代码片段中,我们异步打开一个数据库并且发起一个请求。注册了几个事件处理函数来展示不同的情况。
var request = window.indexedDB.open('数据库名称');
request.onsuccess = function(event) {
var db = this.result;
var transaction = db.transaction([]);
// "readonly" is the default option;
// when data will be added to the database use "readwrite".
var curRequest = transaction.objectStore('ObjectStore Name').openCursor();
curRequest.onsuccess = ...;
};
request.onerror = function(event) {
...;
};
request.onupgradeneeded= function(event) {
// changing objectStore data is done here, as opposed to a transaction enum:
...;
};
Attributes
Attribute | Type | Description |
---|---|---|
result |
readonly any |
Returns the result of the request. If the the request failed and the result is not available, the InvalidStateError exception is thrown. |
error |
readonly DOMError |
The following error codes are returned under certain conditions:
In addition to the error codes sent to the IDBRequest object, asynchronous operations can also raise exceptions. The list describes problems that could occur when the request is being executed, but you might also encounter other problems when the request is being made. For example, if the the request failed and the result is not available, the InvalidStateError exception is thrown. |
source |
readonly Object |
The source of the request, such as an Index or a ObjectStore. If no
source exists (such as when calling |
transaction |
readonly
IDBTransaction |
The transaction for the request. This property can be null for certain
requests, such as for request returned from
IDBFactory.open
(You're just connecting to a database, so there is no transaction to
return).
|
readyState |
readonly enum |
The state of the request. Every request starts in the
|
onerror |
Function |
The event handler for the error event. |
onsuccess |
Function |
The event handler for the success event. |
Constants
readyState
constants
警告:These constants are no longer available. You should use directly the string constants instead. (Firefox bug 887524)
Event handlers
Event handler | Event handler type |
---|---|
onerror |
error |
onsuccess |
success |
Derived interface
规范
Specification |
---|
Indexed Database API 3.0 # request-api |
Browser compatibility
BCD tables only load in the browser