IDBCursor
=========

IndexedDB API の **`IDBCursor`** インターフェイスはデータベースの複数レコードを横断したり繰り返すためのカーソルです。

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

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

**注:** この機能は Web Worker 内で利用可能です

インスタンスプロパティ
-----------

`IDBCursor.source` 読取専用 

カーソルが繰り返している`IDBObjectStore` か `IDBIndex` を返します。この関数は、カーソルが現在繰り返されていたり、繰り返しが終わりを過ぎたり、トランザクションがアクティブでなくても、`null` や例外を返しません。

`IDBCursor.direction` 読取専用 

カーソルの横断の向きを返します。取りうる値については定数を見てください。

`IDBCursor.key` 読取専用 

カーソル位置のレコードのキーを返します。カーソルが範囲外の場合、`undefined` にセットされます。カーソルキーはあらゆるデータ型となりえます。

`IDBCursor.value` 読取専用 

カーソル位置のレコードの値を返します。カーソルの値はあらゆるデータ型となりえます。

`IDBCursor.primaryKey` 読取専用 

カーソルの現在有効な主キーを返します。カーソルが現在繰り返されていたり範囲外で繰り返されていた場合、これは `undefined` にセットされます。カーソルの主キーはあらゆるデータ型となりえます。

インスタンスメソッド
----------

`IDBCursor.advance()`

カーソルが位置を前進させる回数を設定します。

`IDBCursor.continue()`

カーソルを現在の方向の次の位置、省略可能な `key` 引数に当てはまるアイテムに進めます。

`IDBCursor.continuePrimaryKey()`

カーソルを引数で与えられたインデックスキーと主キーに従って設定します。

`IDBCursor.delete()`

`IDBRequest` オブジェクトを返し、別のスレッドでカーソルの位置を変えずにカーソルの位置にあるレコードを削除します。これは、特定のレコードを削除するのに使用できます。

`IDBCursor.update()`

`IDBRequest` オブジェクトを返し、別のスレッドでオブジェクトストア内のカーソルの現在の位置にある値を更新します。これは、特定のレコードを更新するのに使用できます。

定数
--

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

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

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

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


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

  objectStore.openCursor().onsuccess = function (event) {
    var cursor = event.target.result;
    if (cursor) {
      var listItem = document.createElement("li");
      listItem.innerHTML = 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 with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* IndexedDB を使用する
* トランザクションを開始する : `IDBDatabase`
* トランザクションを使用する : `IDBTransaction`
* キーの範囲をセットする : `IDBKeyRange`
* データを取得、変更する : `IDBObjectStore`
* カーソルを使用する : `IDBCursor`
* リファレンスの例 : To-do Notifications (動く例を見る)