IDBCursor: continuePrimaryKey() メソッド

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.

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

continuePrimaryKey() は IDBCursor インターフェイスのメソッドで、カーソルを、キーが引数として指定するキーと一致し、かつ主キーが引数として指定する主キーと一致するアイテムに進めます。

典型的な使用例は、キーを 1 個ずつ比較することなく、前に使用したカーソルが閉じた場所から反復を再開することです。

新しいカーソルのデータを読み込む前にこのメソッドを複数回呼び出す (たとえば、同じ onsuccess ハンドラーで continuePrimaryKey() を 2 回呼び出す) と、カーソルの値を得たフラグがクリアされているため、2 回目の呼び出しで InvalidStateError 例外が発生します。

このメソッドは、インデックスを対象とするカーソルでのみ有効です。オブジェクトストアを対象とするカーソルで使うと、エラーが発生します。

構文

js
continuePrimaryKey(key, primaryKey)

引数

key

カーソルの位置を設定したいキーです。

primaryKey

カーソルの位置を設定したい主キーです。

返値

なし (undefined)。

例外

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

TransactionInactiveError DOMException

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

DataError DOMException

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

  • キーが有効でない
  • キーがカーソルの位置以下であり、かつカーソルの方向が next または nextunique である
  • キーがカーソルの位置以上であり、かつカーソルの方向が prev または prevunique である
InvalidStateError DOMException

カーソルが現在反復中であるか、最後まで反復済みであるとき投げられます。

InvalidAccessError DOMException

カーソルの方向が prev でも next でもないとき投げられます。

例

以下のようにすると、前回の訪問から "javascript" のタグがついた全記事に対する反復を再開できます。

js
let request = articleStore.index("tag").openCursor();
let count = 0;
let unreadList = [];
request.onsuccess = (event) => {
  let cursor = event.target.result;
  if (!cursor) {
    return;
  }
  let lastPrimaryKey = getLastIteratedArticleId();
  if (lastPrimaryKey > cursor.primaryKey) {
    cursor.continuePrimaryKey("javascript", lastPrimaryKey);
    return;
  }
  // lastIteratedArticleId を更新する
  setLastIteratedArticleId(cursor.primaryKey);
  // unreadList に 5 本の記事を追加しておく
  unreadList.push(cursor.value);
  if (++count < 5) {
    cursor.continue();
  }
};

仕様書

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

ブラウザーの互換性

BCD tables only load in the browser

関連情報