IDBObjectStore: add() 方法
注意:此功能在 Web Workers 中可用。
add() 方法是 IDBObjectStore 接口的一部分,它返回一个 IDBRequest 对象,并在单独的线程中创建值的 结构化克隆,然后将克隆后的值存储在对象存储区中。此方法用于向对象存储区添加新记录。
为了确定 add 操作是否已成功完成,除了监听 IDBObjectStore.add 请求的 success 事件之外,还需要监听事务的 complete 事件,因为事务可能在 success 事件触发后仍然失败。换句话说,success 事件仅在事务成功排队时触发。
add 方法是一个仅插入方法。如果对象存储区中已存在一个键(key)与 key 参数相同的记录,则会在返回的请求对象上触发一个 ConstraintError 错误事件。要更新现有记录,您应该改用 IDBObjectStore.put 方法。
语法
add(value)
add(value, key)
参数
返回值
一个 IDBRequest 对象,后续与此操作相关的事件会在此对象上触发。
如果操作成功,请求的 result 属性的值是新记录的键。
异常
此方法可能会抛出以下类型之一的DOMException:
ReadOnlyErrorDOMException-
如果与此操作关联的事务处于只读 模式下,则抛出此异常。
TransactionInactiveErrorDOMException-
如果此
IDBObjectStore的事务不活跃,则会抛出此异常。 DataErrorDOMException-
如果出现以下任一情况,则抛出此异常
- 对象存储区使用内联键(in-line keys)或具有键生成器(key generator),并且提供了 key 参数。
- 对象存储区使用外部键(out-of-line keys)且没有键生成器,并且未提供 key 参数。
- 对象存储区使用内联键但没有键生成器,并且对象存储区的键路径(key path)没有产生有效的键。
- 提供了 key 参数,但它不包含一个有效的键。
InvalidStateErrorDOMException-
如果
IDBObjectStore已被删除或移除,则会抛出此异常。 DataCloneErrorDOMException-
如果正在存储的数据无法通过内部结构化克隆算法进行克隆,则会抛出此异常。
ConstraintErrorDOMException-
如果由于已存在具有相同主键值的记录而导致插入操作失败(违反主键约束),则抛出此异常。
示例
在以下代码片段中,我们打开数据库的读/写事务,并使用 add() 向对象存储区添加一些数据。同时,注意附加到事务事件处理程序上的函数,用于在事务成功或失败时报告事务打开的结果。如需完整的可运行示例,请参阅我们的 待办事项通知 应用(实时查看示例)。
// Let us open our database
const DBOpenRequest = window.indexedDB.open("toDoList", 4);
DBOpenRequest.onsuccess = (event) => {
note.appendChild(document.createElement("li")).textContent =
"Database initialized.";
// 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
const 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
const transaction = db.transaction(["toDoList"], "readwrite");
// report on the success of the transaction completing, when everything is done
transaction.oncomplete = (event) => {
note.appendChild(document.createElement("li")).textContent =
"Transaction completed.";
};
transaction.onerror = (event) => {
note.appendChild(document.createElement("li")).textContent =
"Transaction not opened due to error. Duplicate items not allowed.";
};
// create an object store on the transaction
const objectStore = transaction.objectStore("toDoList");
// Make a request to add our newItem object to the object store
const objectStoreRequest = objectStore.add(newItem[0]);
objectStoreRequest.onsuccess = (event) => {
// report the success of our request
note.appendChild(document.createElement("li")).textContent =
"Request successful.";
};
}
规范
| 规范 |
|---|
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-add① |
浏览器兼容性
加载中…
另见
- 使用 IndexedDB
- 开始事务:
IDBDatabase - 使用事务:
IDBTransaction - 设置键的范围:
IDBKeyRange - 检索和修改数据:
IDBObjectStore - 使用游标:
IDBCursor - 参考示例:待办事项通知(查看实时示例)。