IDBObjectStore.add()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2021.

IDBObjectStore 接口中的 add() 方法返回一个 IDBRequest 对象，在单独的线程中创建一个结构（structured clone）化克隆值，并且在对象存储中存储这个克隆值。这个方法用作在一个对象存储中添加一条新的记录。

要确定添加操作是否成功完成，可以监听事务的 complete 事件。除了 IDBObjectStore.add 请求 success 事件之外，因为事务在成功被触发后仍然可能失败。换句话说，成功事件只有在事务成功排队后才会触发。

add() 方法是唯一的插入方法。如果以关键字参数作为主键的一条记录已经存在在存储对象中，这时在返回的请求对象中 ConstrainError 错误事件将被触发。对于更新存在的记录，你应该使用 IDBObjectStore.put 方法替代它。

备注： 此特性在 Web Worker 中可用。

语法

js
add(value)
add(value, key)

参数

value

需要存储的值。

key 可选

关键字用于识别记录。如果未指明，即为空。

返回

一个 IDBRequest 对象，在该操作对象中触发与此相关的后续事件。

异常

这个方法可能导致以下类型中的一个 DOMException :

Exception Description
ReadOnlyError 与此操作相关联的事务处于只读模式。
TransactionInactiveError 当前 IDBObjectStore 事务不可用。
DataError

适用于以下任何条件：

  • 对象存储使用内联键或者拥有密钥生成器（键生成器），并且提供了键参数。
  • 对象存储使用外联键或者没有密钥生成器（键生成器），并且没有提供键参数。
  • 对象存储使用内联键但是没有密钥生成器（键生成器），并且对象存储的键路径不会产生一个有效的键值。
  • 键参数已经被提供，但是不包含一个有效的键。
InvalidStateError

IDBObjectStore 已经被删除或者移除。
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

参见