IDBObjectStore: put() メソッド
IDBObjectStore
インターフェイスの put()
メソッドは、データベース内の指定のレコードを更新するか、指定のアイテムが存在しない場合は新規レコードを挿入します。
このメソッドは IDBRequest
オブジェクトを返し、別スレッドで、値の構造化複製を作成し、この複製をオブジェクトストアに格納します。これは、トランザクションモードが readwrite
のとき、オブジェクトストアに新規レコードを追加するか既存レコードを更新する用です。レコードが正常に格納されると、返された要求オブジェクトで、result
が格納されたレコードのキーに設定され、transaction
がオブジェクトストアが開かれたトランザクションに設定された success
イベントが発火します。
put
メソッドは 更新または挿入を行う メソッドです。
挿入のみを行う メソッドは、IDBObjectStore.add
メソッドを参照してください。
更新したいレコードを指す IDBCursor
があるときは、IDBObjectStore.put()
を用いるよりも IDBCursor.update()
で更新を行うほうがよいことを覚えておいてください。そうすることで、新規レコードを挿入するのではなく、既存のレコードを更新することが明確になります。
メモ: この機能はウェブワーカー内で利用可能です。
構文
put(item)
put(item, key)
引数
item
-
更新 (または挿入) を行いたいアイテムです。
key
省略可-
更新したいレコードの主キーです。(たとえば
IDBCursor.primaryKey
から取得できます)
返値
この操作に関係する今後のイベントが発火する IDBRequest
オブジェクトです。
操作に成功した場合は、この要求の result
プロパティの値は新しいレコードのキーまたは更新したレコードのキーになります。
例外
このメソッドは、以下の種類のいずれかの DOMException
を投げる可能性があります。
ReadOnlyError
DOMException
-
この操作に対応するトランザクションが読み取り専用モードのとき投げられます。
TransactionInactiveError
DOMException
-
この
IDBObjectStore
のトランザクションが実行中でないとき投げられます。 DataError
DOMException
-
以下のいずれかの条件を満たすとき投げられます。
InvalidStateError
DOMException
-
IDBObjectStore
が削除されたか取り除かれたとき投げられます。 DataCloneError
DOMException
-
保存されるデータが内部の構造化複製アルゴリズムで複製できなかったとき投げられます。
例
以下の例では、レコードタイトルを指定した要求を行います。要求に成功すると、onsuccess
関数で (objectStoreTitleRequest.result
から利用可能な) IDBObjectStore
から対応するレコードを取得し、レコードのプロパティ 1 個を更新し、更新したレコードを put()
を用いた別の要求によりオブジェクトストアに書き戻します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)
const title = "Walk dog";
// いつも通りトランザクションを開く
const objectStore = db
.transaction(["toDoList"], "readwrite")
.objectStore("toDoList");
// タイトルがこの title である to-do リストのオブジェクトを取得する
const objectStoreTitleRequest = objectStore.get(title);
objectStoreTitleRequest.onsuccess = () => {
// 結果として返されたデータオブジェクトを取得する
const data = objectStoreTitleRequest.result;
// オブジェクトの notified の値を "yes" に更新する
data.notified = "yes";
// アイテムをデータベースに書き戻す別の要求を生成する
const updateTitleRequest = objectStore.put(data);
// この要求を開始したトランザクションを記録する
console.log(
`この要求を開始したトランザクションは ${updateTitleRequest.transaction}`,
);
// 新しい要求が成功したら、再び displayData() 関数を実行し、表示を更新する
updateTitleRequest.onsuccess = () => {
displayData();
};
};
仕様書
Specification |
---|
Indexed Database API 3.0 # ref-for-dom-idbobjectstore-put① |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- IndexedDB の使用
- トランザクションの開始:
IDBDatabase
- トランザクションの使用:
IDBTransaction
- キー範囲の設定:
IDBKeyRange
- データの取得と変更:
IDBObjectStore
- カーソルの使用:
IDBCursor
- リファレンス例: To-do Notifications (動くデモを見る)