IDBKeyRange: bound() 静的メソッド

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.

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

bound() は IDBKeyRange インターフェイスのメソッドで、指定の上限と下限の値を持つ新しいキーの範囲を生成します。範囲は開 (すなわち、端点の値は範囲に含まれない) とすることも、閉 (すなわち、端点の値は範囲に含まれる) とすることもできます。既定では、範囲は閉になります。

構文

js
IDBKeyRange.bound(lower, upper)
IDBKeyRange.bound(lower, upper, lowerOpen)
IDBKeyRange.bound(lower, upper, lowerOpen, upperOpen)

引数

lower

新しいキーの範囲の下限を指定します。

upper

新しいキーの範囲の上限を指定します。

lowerOpen 省略可

下限が端点の値を除くかどうかを示します。既定値は false です。

upperOpen 省略可

上限が端点の値を除くかどうかを示します。既定値は false です。

返値

新しく生成されたキーの範囲を表す IDBKeyRange です。

例外

DataError DOMException

以下の条件のいずれかを満たしたとき投げられます。

  • 下限または上限の引数に有効なキーが渡されなかった
  • 下限のキーが上限のキーより大きい
  • 下限のキーと上限のキーが一致し、いずれかの境界が開である

例

以下の例では、有界のキーの範囲の使用法を示します。keyRangeValue = IDBKeyRange.bound("A", "F"); と宣言します。これは、"A" と "F" の間の値を表す範囲です。(IDBTransaction により) トランザクションを開き、オブジェクトストアを開き、省略可能なキーの範囲の値を keyRangeValue として IDBObjectStore.openCursor でカーソルを開きます。これにより、このカーソルは指定した範囲に含まれるキーを持つレコードのみを取り出します。端点を開として宣言していないので、この範囲は値 "A" および "F" を含みます。IDBKeyRange.bound("A", "F", true, true); を用いた場合は、"A" および "F" は範囲に含まれず、その間の値のみが含まれます。

メモ: キーの範囲に関する実験ができるより完全な例は、indexeddb-examples リポジトリーの idbkeyrange ディレクトリーを参照してください。(動く例も見る)

js
function displayData() {
  const keyRangeValue = IDBKeyRange.bound("A", "F");

  const transaction = db.transaction(["fThings"], "readonly");
  const objectStore = transaction.objectStore("fThings");

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

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

仕様書

Specification
Indexed Database API 3.0
# ref-for-dom-idbkeyrange-bound①

ブラウザーの互換性

BCD tables only load in the browser

関連情報