IDBObjectStore: add() メソッド

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

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

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

メモ: この機能はウェブワーカー内で利用可能です。

構文

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

関連情報