IDBObjectStore.add()
====================

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

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

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

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

语法
--
```

var request = objectStore.add(value);
var request = objectStore.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
-------------

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-add① |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* 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.)