IDBObjectStore: add() 方法
注意: 此功能在 Web Workers 中可用。
add()
方法是 IDBObjectStore
接口的方法,它返回一个 IDBRequest
对象,并在单独的线程中创建值的 结构化克隆,并将克隆后的值存储在对象存储中。此方法用于将新记录添加到对象存储中。
要确定添加操作是否已成功完成,除了监听 IDBObjectStore.add
请求的 success
事件外,还需要监听事务的 complete
事件,因为在 success
事件触发后,事务仍可能失败。换句话说,success
事件仅在事务成功排队时触发。
add
方法是仅插入方法。如果对象存储中已存在使用 key
参数作为键的记录,则在返回的请求对象上会触发错误 ConstraintError
事件。要更新现有记录,应使用 IDBObjectStore.put
方法。
语法
add(value)
add(value, key)
参数
返回值
一个 IDBRequest
对象,后续与该操作相关的事件将在该对象上触发。
如果操作成功,请求的 result
属性的值将是新记录的键。
异常
此方法可能会引发以下类型的 DOMException
ReadOnlyError
DOMException
-
如果与该操作关联的事务处于只读 模式,则会抛出该异常。
TransactionInactiveError
DOMException
-
如果此
IDBObjectStore
的事务处于非活动状态,则会抛出该异常。 DataError
DOMException
-
如果出现以下任何情况,则会抛出该异常
- 对象存储使用内联键或具有键生成器,并且提供了键参数。
- 对象存储使用外联键并且没有键生成器,并且未提供键参数。
- 对象存储使用内联键但没有键生成器,并且对象存储的键路径未生成有效键。
- 提供了键参数,但它不包含有效键。
InvalidStateError
DOMException
-
如果
IDBObjectStore
已被删除或移除,则会抛出该异常。 DataCloneError
DOMException
-
如果要存储的数据无法通过内部结构化克隆算法克隆,则会抛出该异常。
ConstraintError
DOMException
-
如果插入操作因违反主键约束而失败(由于已存在具有相同主键值的记录),则会抛出该异常。
示例
在以下代码片段中,我们对数据库打开了一个读写事务,并使用 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① |
浏览器兼容性
BCD 表格仅在启用 JavaScript 的浏览器中加载。
另请参见
- 使用 IndexedDB
- 启动事务:
IDBDatabase
- 使用事务:
IDBTransaction
- 设置键范围:
IDBKeyRange
- 检索和更改数据:
IDBObjectStore
- 使用游标:
IDBCursor
- 参考示例:待办事项通知 (查看示例).