IDBIndex: openCursor() メソッド

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.

IDBIndex インターフェイスの openCursor() メソッドは、IDBRequest オブジェクトを返し、別スレッドで、指定のキー範囲を走査するカーソルを生成します。

このメソッドは、指定された方向に基づいて、カーソルの位置を適切なレコードに設定します。

キー範囲が指定されないか null の場合は、範囲は全レコードを含みます。

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

構文

js
openCursor()
openCursor(range)
openCursor(range, direction)

引数

range 省略可

カーソルの範囲として使用するキーまたは IDBKeyRange です。省略した場合は、このオブジェクトストア内の全レコードを選択するキー範囲になります。

direction 省略可

カーソルの方向です。取りうる値は、IDBCursor の定数を参照してください。

返値

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

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

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

例外

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

TransactionInactiveError DOMException

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

TypeError

引数 direction の値が無効であるとき投げられます。

DataError DOMException

与えられたキーまたはキー範囲が無効なキーを含むとき投げられます。

InvalidStateError DOMException

この IDBIndex が削除されたか取り除かれたとき投げられます。

例

以下の例では、トランザクションとオブジェクトストアを開き、シンプルな連絡先データベースからインデックス lName を取得します。そして、このインデックスで openCursor() により基本的なカーソルを開きます。これは、返されるレコードが主キーではなくこのインデックスに基づいてソートされる以外、ObjectStore で直接 IDBObjectStore.openCursor を用いてカーソルを開くのと同じように動きます。

最後に、各レコードを走査し、データを HTML テーブルに挿入します。動く例全体は、IndexedDB-examples デモレポジトリーを参照してください。(動く例を見る)

js
function displayDataByIndex() {
  tableEntry.innerHTML = "";
  const transaction = db.transaction(["contactsList"], "readonly");
  const objectStore = transaction.objectStore("contactsList");

  const myIndex = objectStore.index("lName");

  myIndex.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      tableRow.innerHTML =
        `<td>${cursor.value.id}</td>` +
        `<td>${cursor.value.lName}</td>` +
        `<td>${cursor.value.fName}</td>` +
        `<td>${cursor.value.jTitle}</td>` +
        `<td>${cursor.value.company}</td>` +
        `<td>${cursor.value.eMail}</td>` +
        `<td>${cursor.value.phone}</td>` +
        `<td>${cursor.value.age}</td>`;
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("全エントリーを表示しました。");
    }
  };
}

仕様書

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

ブラウザーの互換性

BCD tables only load in the browser

関連情報