IDBObjectStore: openCursor() メソッド

IDBObjectStore インターフェイスの openCursor() メソッドは、IDBRequest オブジェクトを返し、別スレッドで新しい IDBCursorWithValue オブジェクトを返します。カーソルを用いてオブジェクトストアを走査するのに用います。

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

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

構文

js
openCursor()
openCursor(query)
openCursor(query, direction)

引数

query 省略可

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

direction 省略可

カーソルが動く方向を決める文字列です。デフォルトは next です。以下の値が有効です。

next

カーソルはオブジェクトストアの最初で開き、キーの昇順で重複を含むすべてのレコードを返します。

nextunique

カーソルはオブジェクトストアの最初で開き、キーの昇順で重複を除いたすべてのレコードを返します。

prev

カーソルはオブジェクトストアの最初で開き、キーの降順で重複を含むすべてのレコードを返します。

prevunique

カーソルはオブジェクトストアの最初で開き、キーの降順で重複を除いたすべてのレコードを返します。

返値

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

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

  • 与えられたクエリーにマッチする最初のレコードを指す IDBCursorWithValue オブジェクト
  • マッチするレコードが見つからなかった場合は 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.openCursor();
request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    // cursor.value に走査中の現在のレコードが入っている
    // ここで結果を用いて何かする
    cursor.continue();
  } else {
    // もう結果は無い
  }
};

仕様書

Specification
Indexed Database API 3.0
# ref-for-dom-idbobjectstore-opencursor②

ブラウザーの互換性

BCD tables only load in the browser

関連情報