IDBKeyRange.bound()

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

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

構文

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

関連情報