IDBObjectStore: openCursor() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2015年7月⁩.

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

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

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

構文

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: 指定されたキーまたはキー範囲が無効であるとき投げられます。

例

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

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②

ブラウザーの互換性

Help improve MDN

Learn how to contribute

This page was last modified on ⁨2023年9月4日⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content