IDBCursor

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.

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

メモ: IDBCursorWithValue と混同しないでください。これは IDBCursor インターフェイスに value プロパティを追加しただけのものです。

IDBCursor は IndexedDB API のインターフェイスで、複数レコードを走査したり繰り返し処理をしたりするためのカーソルです。

このカーソルはどのインデックスやオブジェクトをループしているかを示す情報源です。これは範囲内の位置を示し、レコードのキー順に増減して動きます。カーソルにより、アプリケーションからカーソル範囲内の全レコードに非同期に処理できます。

一度に無制限の数のカーソルを持つことができます。あるカーソルを表す同一の IDBCursor オブジェクトを取得できます。操作はインデックスやオブジェクトストアに対して実行されます。

インスタンスプロパティ

メモ: IDBCursorWithValue は IDBCursor インターフェイスに value プロパティを追加したものです。

IDBCursor.source 読取専用: カーソルが繰り返しているIDBObjectStore か IDBIndex を返します。この関数は、カーソルが現在繰り返されていたり、繰り返しが終わりを過ぎたり、トランザクションがアクティブでなくても、null や例外を返しません。
IDBCursor.direction 読取専用: カーソルの走査の移動方向を返します。
IDBCursor.key 読取専用: カーソル位置のレコードのキーを返します。カーソルが範囲外の場合、undefined にセットされます。カーソルキーはあらゆるデータ型となりえます。
IDBCursor.primaryKey 読取専用: カーソルの現在有効な主キーを返します。カーソルが現在繰り返されていたり範囲外で繰り返されていた場合、これは undefined にセットされます。カーソルの主キーはあらゆるデータ型となりえます。
IDBCursor.request 読取専用: カーソルを使用した IDBRequest を返します。

インスタンスメソッド

IDBCursor.advance(): カーソルが位置を前進させる回数を設定します。
IDBCursor.continue(): カーソルを現在の方向の次の位置、省略可能な key 引数に当てはまるアイテムに進めます。
IDBCursor.continuePrimaryKey(): カーソルを引数で与えられたインデックスキーと主キーに従って設定します。
IDBCursor.delete(): IDBRequest オブジェクトを返し、別のスレッドでカーソルの位置を変えずにカーソルの位置にあるレコードを削除します。これは、特定のレコードを削除するのに使用できます。
IDBCursor.update(): IDBRequest オブジェクトを返し、別のスレッドでオブジェクトストア内のカーソルの現在の位置にある値を更新します。これは、特定のレコードを更新するのに使用できます。

定数

非推奨;: この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

警告: これらの定数は利用できません。Gecko 25 で削除されました。代わりに文字列定数を直接使う必要があります。(Firefox バグ 891944)

NEXT: "next" : カーソルは重複を含む全てのレコードを提示します。キーの範囲の下限から開始し、上方向に動きます。(キーの順番に単調増加します)
NEXTUNIQUE : "nextunique" : カーソルは重複を除いた全てのレコードを提示します。同じキーを持つ複数のレコードが存在する場合、走査の順で最初のレコードのみを取得できます。キーの範囲の下限から開始し、上方向に動きます。
PREV: "prev" : カーソルは重複を含む全てのレコードを提示します｡キーの範囲の上限から開始し､下方向に動きます｡(キーの順番に単調減少します)
PREVUNIQUE: "prevunique" : カーソルは重複を除いた全てのレコードを提示します｡同じキーを持つ複数のレコードが存在する場合､走査の順で最初のレコードのみを取得できます｡キーの範囲の上限から開始し､下方向に動きます｡

この単純なコードスニペットでは、トランザクションを生成し、オブジェクトストアを取得し、そしてカーソルを用いてオブジェクトストア内の全レコードを走査します。カーソルを使う場合、データをキーを用いて選択する必要はなく、単に全部を取得できます。ループにおけるそれぞれの繰り返しにおいて、カーソルオブジェクトの現在のレコードから cursor.value.foo でデータを取り出せることにも注目してください。動く例全体は、IDBCursor example を参照してください。(動く例を見る)

function displayData() {
  const transaction = db.transaction(["rushAlbumList"], "readonly");
  const objectStore = transaction.objectStore("rushAlbumList");

  objectStore.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const listItem = document.createElement("li");
      listItem.textContent = `${cursor.value.albumTitle}, ${cursor.value.year}`;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log("項目をすべて表示しました。");
    }
  };
}

仕様書

Specification
Indexed Database API 3.0 # cursor-interface

ブラウザーの互換性

BCD tables only load in the browser

インスタンスプロパティ

インスタンスメソッド

定数

例

仕様書

ブラウザーの互換性

関連情報