IDBObjectStore: openKeyCursor() メソッド

IDBObjectStore インターフェイスの openKeyCursor() メソッドは、result がマッチした結果の走査に用いることができる IDBCursor に設定される IDBRequest オブジェクトを返します。カーソルを用いてオブジェクトストア内のキーを走査するのに用います。

追加を行う操作が正常に完了したかを判定するには、結果の success イベントを監視してください。

構文

js
openKeyCursor()
openKeyCursor(query)
openKeyCursor(query, direction)

引数

query 省略可

問い合わせを行うキー範囲です。単一のキーが渡された場合は、そのキーのみを含むキー範囲になります。何も渡されなかった場合は、オブジェクトストア内の全レコードを選択するキー範囲になります。

direction 省略可

カーソルが動く方向を決める IDBCursorDirection です。 有効な値は "next"、"nextunique"、"prev"、"prevunique" です。デフォルトは "next" です。

返値

この操作に関係する今後のイベントが発火する IDBRequest オブジェクトです。

操作に成功した場合は、この要求の result プロパティの値は以下になります。

  • 与えられたクエリーにマッチする最初のレコードを指す IDBCursor オブジェクト
  • マッチするレコードが見つからなかった場合は null

例外

このメソッドは、以下の種類のいずれかの DOMException を投げる可能性があります。

InvalidStateError DOMException

この IDBObjectStore または IDBIndex が削除済のとき投げられます。

TransactionInactiveError DOMException

この IDBObjectStore のトランザクションが実行中でないとき投げられます。

DataError DOMException

指定のキーまたはキー範囲が無効であるとき投げられます。

例

このシンプルな断片では、トランザクションを生成し、オブジェクトストアを取得し、カーソルを用いてオブジェクトストア内の全レコードを走査します。

js
const transaction = db.transaction("name", "readonly");
const objectStore = transaction.objectStore("name");
const request = objectStore.openKeyCursor();
request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    // cursor.key に走査中の現在のレコードのキーが入っている
    // openCursor と違って cursor.value は無いことに注意
    // ここで結果を用いて何かする
    cursor.continue();
  } else {
    // もう結果は無い
  }
};

仕様書

Specification
Indexed Database API 3.0
# ref-for-dom-idbobjectstore-openkeycursor①

ブラウザーの互換性

BCD tables only load in the browser

関連情報