IDBObjectStore: add() メソッド
==========================

`IDBObjectStore` インターフェイスの **`add()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで値の構造化複製を生成し、この複製をオブジェクトストアに保存します。これはオブジェクトストアに新しいレコードを追加する操作です。

`success` イベントが発火した後でもトランザクションは失敗するかもしれないので、追加操作が正常に完了したかを判定するには、`IDBObjectStore.add` 要求の `success` イベントに加え、トランザクションの `complete` イベントも監視してください。言い換えると、`success` イベントはトランザクションをキューに追加するのに成功した時点で発火します。

`add` メソッドは *挿入のみを行う* メソッドです。引数 `key` をキーとするレコードがオブジェクトストア内に既に存在する場合、返される要求オブジェクトで `ConstraintError` のエラーイベントが発火します。既存のレコードを更新するには、かわりに `IDBObjectStore.put` を用いてください。

**注:** この機能は Web Worker 内で利用可能です

構文
--


```js
add(value)
add(value, key)
```

### 引数

`value`

保存する値です。

`key` 省略可

レコードを識別するキーです。指定されない場合は、`null` になります。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は新しいレコードのキーになります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`ReadOnlyError` `DOMException`

この操作に対応するトランザクションが読み取り専用モードのとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

以下のいずれかの条件を満たすとき投げられます。

* オブジェクトストアがインラインキーを用いているかキージェネレーターが存在し、引数 `key` が指定されたとき。
* オブジェクトストアがアウトラインキーを用いかつキージェネレーターも存在せず、引数 `key` が指定されないとき。
* オブジェクトストアがインラインキーを用いているがキージェネレーターは存在せず、オブジェクトストアのキーパスが有効なキーを生成しないとき。
* 引数 `key` が指定されたが、有効なキーでないとき。

`InvalidStateError` `DOMException`

`IDBObjectStore` が削除されたか取り除かれたとき投げられます。

`DataCloneError` `DOMException`

保存されるデータが内部の構造化複製アルゴリズムで複製できなかったとき投げられます。

`ConstraintError` `DOMException`

主キー制約の違反により挿入操作に失敗したとき投げられます。(同じ主キーの値を持つレコードが既に存在するとき)

例
-

以下のコード断片では、データベースの読み書きトランザクションを開き、`add()` を用いてオブジェクトストアにデータを追加します。トランザクションイベントハンドラーに設定された関数により、成功時または失敗時、トランザクションを開いた結果を報告することにも注目してください。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)


```js
// データベースを開く
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を変数 db に格納する
  // これは後でよく使う
  db = DBOpenRequest.result;

  // addData() 関数を実行し、データをデータベースに追加する
  addData();
};

function addData() {
  // IDB に挿入できる新規オブジェクトを生成する
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // 読み書きトランザクションを開き、データを追加する準備をする
  const transaction = db.transaction(["toDoList"], "readwrite");

  // すべて完了したとき、トランザクションの正常終了を報告する
  transaction.oncomplete = (event) => {
    note.innerHTML += "<li>トランザクションが完了しました。</li>";
  };

  transaction.onerror = (event) => {
    note.innerHTML +=
      "<li>トランザクションはエラーのため開けませんでした。アイテムは重複させられません。</li>";
  };

  // トランザクションでオブジェクトストアを生成する
  const objectStore = transaction.objectStore("toDoList");

  // オブジェクトストアに newItem オブジェクトを追加する要求をする
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // 要求の成功を報告する
    note.innerHTML += "<li>要求に成功しました。</li>";
  };
}
```

仕様書
---

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

ブラウザーの互換性
---------

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)