IDBIndex: openKeyCursor() メソッド

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.

We’d love to hear your thoughts on the next set of proposals for the JavaScript language. You can find a description of the proposals here.
Please take two minutes to fill out our short survey.

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

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

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

メモ: openKeyCursor() が返すカーソルは、IDBIndex.openCursor とは違い、参照される値を用意しません。 これにより、キーのリストをより効率よく得ることができます。

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

構文

js
openKeyCursor()
openKeyCursor(range)
openKeyCursor(range, direction)

引数

range 省略可

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

direction 省略可

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

返値

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

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

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

例外

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

TransactionInactiveError DOMException

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

TypeError

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

DataError DOMException

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

InvalidStateError DOMException

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

例

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

最後に、各レコードを走査し、ラストネームと対応するレコードの主キーを HTML テーブルに挿入します。

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

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

  myIndex.openKeyCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      tableRow.innerHTML =
        `<td>${cursor.key}</td>` + `<td>${cursor.primaryKey}</td>`;
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("全ラストネームを表示しました。");
    }
  };
}

仕様書

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

ブラウザーの互換性

関連情報