IDBCursor: advance() メソッド

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.

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

advance() は IDBCursor インターフェイスのメソッドで、このカーソルが位置を前進させる回数を設定します。

構文

js
advance(count)

引数

count

カーソルが前進する回数

返値

なし (undefined)。

例外

このメソッドは次のいずれかの DOMException を発生することがあります。

TransactionInactiveError DOMException

この IDBCursor のトランザクションは活性化していません。

TypeError

count パラメーターに渡された値がゼロや負の数です。

InvalidStateError DOMException

カーソルは現在繰り返し中か、最後を過ぎています。

例

このシンプルな例では、トランザクションを作成し、オブジェクトストアを取得し、オブジェクトストアのレコードを一通り繰り返すカーソルを使っています。ここで cursor.advance(2) を使ってそれぞれ 2 回前進していて、つまり 1 つおきの結果だけが表示されます。advance() は IDBCursor.continue と同様に動作しますが、常に次のレコードに移動するのでなく、一度に複数のレコードを飛び越えられるのが違います。

注意点としてループの繰り返しで、カーソルオブジェクトの現在のレコードのテータを cursor.value.fooを使って取得できます。完全な動作例は、IDBCursor の例(ライブ例を見る)を見てください。

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

  objectStore.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const listItem = document.createElement("li");
      listItem.textContent = `${cursor.value.albumTitle}, ${cursor.value.year}`;
      list.appendChild(listItem);
      cursor.advance(2);
    } else {
      console.log("全項目を 1 つおきに表示しました。");
    }
  };
}

仕様書

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

ブラウザーの互換性

BCD tables only load in the browser

関連情報