IDBKeyRange.bound()

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

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

構文

js
bound(lower, upper)
bound(lower, upper, lowerOpen)
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

関連情報