IDBObjectStore.add()
IDBObjectStore
接口中的 add()
方法返回一个 IDBRequest
对象,在单独的线程中创建一个结构(structured clone)化克隆值,并且在对象存储中存储这个克隆值。这个方法用作在一个对象存储中添加一条新的记录。
要确定添加操作是否成功完成,可以监听事务的 complete
事件。除了 IDBObjectStore.add
请求 success
事件之外,因为事务在成功被触发后仍然可能失败。换句话说,成功事件只有在事务成功排队后才会触发。
add()
方法是唯一的插入方法。如果以关键字参数作为主键的一条记录已经存在在存储对象中,这时在返回的请求对象中 ConstrainError
错误事件将被触发。对于更新存在的记录,你应该使用 IDBObjectStore.put
方法替代它。
备注: 此特性在 Web Worker 中可用。
语法
js
add(value)
add(value, key)
参数
返回
一个 IDBRequest
对象,在该操作对象中触发与此相关的后续事件。
异常
这个方法可能导致以下类型中的一个 DOMException
:
Exception | Description |
---|---|
ReadOnlyError |
与此操作相关联的事务处于只读模式。 |
TransactionInactiveError |
当前 IDBObjectStore 事务不可用。 |
DataError |
适用于以下任何条件:
|
InvalidStateError |
|
DataCloneError |
通过内部结构的克隆算法,被存储的数据无法被克隆 |
ConstraintError |
因为主键违法规定导致的插入操作失败(由于已存在的记录使用了相同的主键值)。 |
示例
在以下的代码片段中,在我们数据库中打开一个 read/write(读写)事务和使用 add()
方法添加一些数据到存储对象中。还要注意附加到事务事件处理程序的函数,这些函数用于报告事务打开成功或失败时的结果。完整的示例代码,请查看我们的 To-do Notifications 应用(在线查看示例)。
js
// Let us open our database
var DBOpenRequest = window.indexedDB.open("toDoList", 4);
DBOpenRequest.onsuccess = function (event) {
note.innerHTML += "<li>Database initialised.</li>";
// store the result of opening the database in the db variable.
// This is used a lot below
db = DBOpenRequest.result;
// Run the addData() function to add the data to the database
addData();
};
function addData() {
// Create a new object ready to insert into the IDB
var newItem = [
{
taskTitle: "Walk dog",
hours: 19,
minutes: 30,
day: 24,
month: "December",
year: 2013,
notified: "no",
},
];
// open a read/write db transaction, ready for adding the data
var transaction = db.transaction(["toDoList"], "readwrite");
// report on the success of the transaction completing, when everything is done
transaction.oncomplete = function (event) {
note.innerHTML += "<li>Transaction completed.</li>";
};
transaction.onerror = function (event) {
note.innerHTML +=
"<li>Transaction not opened due to error. Duplicate items not allowed.</li>";
};
// create an object store on the transaction
var objectStore = transaction.objectStore("toDoList");
// Make a request to add our newItem object to the object store
var objectStoreRequest = objectStore.add(newItem[0]);
objectStoreRequest.onsuccess = function (event) {
// report the success of our request
note.innerHTML += "<li>Request successful.</li>";
};
}
规范
Specification |
---|
Indexed Database API 3.0 # ref-for-dom-idbobjectstore-add① |
浏览器兼容性
BCD tables only load in the browser
参见
- Using IndexedDB
- Starting transactions:
IDBDatabase
- Using transactions:
IDBTransaction
- Setting a range of keys:
IDBKeyRange
- Retrieving and making changes to your data:
IDBObjectStore
- Using cursors:
IDBCursor
- Reference example: To-do Notifications (view example live.)