IDBKeyRange

IndexedDB API 的IDBKeyRange接口表示一些数据类型上的键的连续间隔。可以使用一个键或某个范围的键从IDBObjectStoreIDBIndex 对象中检索记录。您也可以指定键的上界和下界来限制范围。例如,您可以遍历值范围a - z中的键的所有值。

键范围可以是单个值,也可以是具有上界、下界或端点的范围。如果键范围同时有上界或下界,那么它是有界的,否则是无界的。有界键范围可以是开放的(不包含端点)或闭合的(包含了端点)。要检索一定范围内的所有键值,可以使用以下的代码结构:

Range Code
All keys ≤ x IDBKeyRange.upperBound(x)
All keys < x IDBKeyRange.upperBound(x, true)
All keys ≥ y IDBKeyRange.lowerBound(y)
All keys > y IDBKeyRange.lowerBound(y, true)
All keys ≥ x && ≤ y IDBKeyRange.bound(x, y)
All keys > x &&< y IDBKeyRange.bound(x, y, true, true)
All keys > x && ≤ y IDBKeyRange.bound(x, y, true, false)
All keys ≥ x &&< y IDBKeyRange.bound(x, y, false, true)
The key = z IDBKeyRange.only(z)

如果以下条件为true,则键包含在键范围中:

  • 键范围的下界值为以下值或符合以下条件之一时:
    • undefined
    • 低于正在被鉴定的键值
    • 等于正在被鉴定的键值,且键范围的lowerOpen属性false.
  • 键范围的上界值为以下值或符合以下条件之一时:
    • undefined
    • 高于正在被鉴定的键值
    • 等于正在被鉴定的键值,且键范围的upperOpen属性为false.

Note:

此特性在 Web Worker 中可用。

Properties

IDBKeyRange.lower 只读
键范围的下界
IDBKeyRange.upper 只读
键范围的上界
IDBKeyRange.lowerOpen 只读
如果下界值包含在键范围内,则返回false。
IDBKeyRange.upperOpen 只读
如果上界值包含在键范围内,则返回false。

Methods

Static methods

IDBKeyRange.bound()
指定上界和下界来创建一个新的键范围
IDBKeyRange.only()
指定单个键值来创建一个新的键范围
IDBKeyRange.lowerBound()
指定结果集的下界来创建一个新的键范围
IDBKeyRange.upperBound()
指定结果集的上界来创建一个新的键范围

Instance methods

IDBKeyRange.includes()
返回一个布尔值来表示指定的键是否在键范围内。

Examples

以下示例用以说明该如果使用键范围。在此我们将 keyRangeValue 声明为A~F之间的范围。我们打开一个事务 (使用 IDBTransaction) 和一个对象存储, 并用 IDBObjectStore.openCursor打开一个游标,其中keyRangeValue是一个可选的键范围值,指定之后游标将只检索键在该范围内的记录。这里的键范围包括了“A”和“F”,因为我们还没声明键范围为开放边界。如果我们使用 IDBKeyRange.bound("A", "F", true, true);,那么这个键范围将不包括“A”和“F”,只包含它们之间的值。

Note: For a more complete example allowing you to experiment with key range, have a look at our IDBKeyRange-example repo (view the example live too.)

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

  var transaction = db.transaction(['fThings'], 'readonly');
  var objectStore = transaction.objectStore('fThings');

  objectStore.openCursor(keyRangeValue).onsuccess = function(event) {
    var cursor = event.target.result;
    if(cursor) {
      var listItem = document.createElement('li');
      listItem.innerHTML = '<strong>' + cursor.value.fThing + '</strong>, ' + cursor.value.fRating;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log('Entries all displayed.');
    }
  };
}

Specifications

Specification Status Comment
Indexed Database API 2.0
IDBKeyRange
Recommendation Initial definition.
Indexed Database API 2.0
IDBKeyRange
Recommendation Adds includes().

Browser compatibility

BCD tables only load in the browser

See also