IDBCursor: update() メソッド

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.

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

update() は IDBCursor インターフェイスのメソッドで、IDBRequest オブジェクトを返し、別のスレッドで、オブジェクトストア内のカーソルが現在指している値を更新します。カーソルが削除したばかりのレコードを指している場合は、新しいレコードが作成されます。

注意点として、update() (や IDBCursor.delete()) を IDBIndex.openKeyCursor() で取得したカーソルで呼ぶことはできません。このような用途のためには、かわりに IDBIndex.openCursor() を使用しないといけません。

構文

js
update(value)

引数

value

現在の位置に保存する新しい値です。

返値

この操作に関連する後続のイベントが発生する IDBRequest オブジェクト。

処理が成功した場合、リクエストの result プロパティの値は undefined です。

例外

このメソッドは、以下の種類の DOMException を発生させる可能性があります。

TransactionInactiveError DOMException

この IDBCursor のトランザクションが活性状態でないとき投げられます。

ReadOnlyError DOMException

トランザクションが読み取り専用モードであるとき投げられます。

InvalidStateError DOMException

カーソルが IDBindex.openKeyCursor により作成されたか、現在反復中であるか、最後まで反復済みであるとき投げられます。

DataError DOMException

操作対象のオブジェクトストアがインラインキーを使用しており、オブジェクトストアのキーパスで指定された値のプロパティがこのカーソルの位置のキーと一致しないとき投げられます。

DataCloneError DOMException

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

例

このシンプルな断片では、トランザクションを作成し、オブジェクトストアを取得し、カーソルを用いてオブジェクトストア内の全レコードを走査します。カーソルが現在指しているレコードの albumTitle が "A farewell to kings" である場合、const request = cursor.update(); を用いてアルバムのリリース年を更新します。

なお、データの完全性が破壊されるため、cursor.update() により主キーを変更することはできません。そのため、アルバムのタイトルは変更していません。このような場合、レコード全体を削除し、IDBObjectStore.add により新しいレコードを追加する必要があるでしょう。また、更新の呼び出しに直接 cursor.value を使うことはできません。そのため、以下の例では作業用に変数 updateData を使用しています。

カーソルを用いる場合、データをキーで選択する必要は無く、単に全てを取得できます。また、ループ中のそれぞれの繰り返しにおいて、カーソルオブジェクトが現在指しているレコードのデータを cursor.value.foo のようにして取得できます。動く例全体は、IDBCursor example を参照してください。(動く例を見る)

js
function updateResult() {
  list.textContent = "";
  const transaction = db.transaction(["rushAlbumList"], "readwrite");
  const objectStore = transaction.objectStore("rushAlbumList");

  objectStore.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      if (cursor.value.albumTitle === "A farewell to kings") {
        const updateData = cursor.value;

        updateData.year = 2050;
        const request = cursor.update(updateData);
        request.onsuccess = () => {
          console.log("アルバムの年の改善？");
        };
      }

      const listItem = document.createElement("li");
      listItem.textContent = `${cursor.value.albumTitle}, ${cursor.value.year}`;
      list.appendChild(listItem);
      cursor.continue();
    } else {
      console.log("エントリーを表示しました。");
    }
  };
}

仕様書

Specification
Indexed Database API 3.0
# ref-for-dom-idbcursor-update①

ブラウザーの互換性

BCD tables only load in the browser

関連情報