IDBIndex: openKeyCursor() Methode

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.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die openKeyCursor() Methode des IDBIndex-Interfaces gibt ein IDBRequest-Objekt zurück und erstellt in einem separaten Thread einen Cursor über den angegebenen Schlüsselbereich, wie durch diesen Index sortiert.

Die Methode setzt die Position des Cursors auf den entsprechenden Schlüssel, basierend auf der angegebenen Richtung.

Wenn der Schlüsselbereich nicht spezifiziert oder null ist, umfasst der Bereich alle Schlüssel.

Hinweis: Die Cursors, die von openKeyCursor() zurückgegeben werden, stellen den referenzierten Wert nicht so zur Verfügung wie IDBIndex.openCursor. Dies macht das Abrufen einer Liste von Schlüsseln wesentlich effizienter.

Syntax

js
openKeyCursor()
openKeyCursor(range)
openKeyCursor(range, direction)

Parameter

range Optional

Ein Schlüssel oder IDBKeyRange, der als Bereich des Cursors verwendet wird. Wenn nichts übergeben wird, wird dies standardmäßig zu einem Schlüsselbereich, der alle Datensätze in diesem Objekt-Store auswählt.

direction Optional

Die Richtung des Cursors. Siehe IDBCursor Konstanten für mögliche Werte.

Rückgabewert

Ein IDBRequest-Objekt, auf dem nachfolgende Ereignisse, die sich auf diese Operation beziehen, ausgelöst werden.

Wenn die Operation erfolgreich ist, ist der Wert der result-Eigenschaft des Requests:

  • ein IDBCursor-Objekt, das auf den ersten Datensatz zeigt, der der gegebenen Abfrage entspricht
  • null, wenn keine übereinstimmenden Datensätze gefunden wurden.

Ausnahmen

Diese Methode kann eine DOMException eines der folgenden Typen auslösen:

TransactionInactiveError DOMException

Wird ausgelöst, wenn die Transaktion dieses IDBIndex inaktiv ist.

TypeError

Wird ausgelöst, wenn der Wert für den Parameter direction ungültig ist.

DataError DOMException

Wird ausgelöst, wenn der angegebene Schlüssel oder Schlüsselbereich einen ungültigen Schlüssel enthält.

InvalidStateError DOMException

Wird ausgelöst, wenn der IDBIndex gelöscht oder entfernt wurde.

Beispiele

Im folgenden Beispiel öffnen wir eine Transaktion und einen Objekt-Store und erhalten dann den Index lName aus einer einfachen Kontaktdatenbank. Anschließend öffnen wir einen Schlüsselcursor auf dem Index mit openKeyCursor() — dies funktioniert genauso wie das Öffnen eines Cursors direkt auf einem ObjectStore mit IDBObjectStore.openKeyCursor, außer dass die zurückgegebenen Datensätze basierend auf dem Index und nicht dem Primärschlüssel sortiert werden.

Schließlich iterieren wir durch jeden Datensatz im Index und fügen den Nachnamen und den entsprechenden Primärschlüssel des referenzierten Datensatzes in eine HTML-Tabelle ein.

js
function displayDataByIndex() {
  tableEntry.textContent = "";
  const transaction = db.transaction(["contactsList"], "readonly");
  const objectStore = transaction.objectStore("contactsList");

  const myIndex = objectStore.index("lName");

  myIndex.openKeyCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      tableRow.appendChild(document.createElement("td")).textContent =
        cursor.key;
      tableRow.appendChild(document.createElement("td")).textContent =
        cursor.primaryKey;
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("All last names displayed.");
    }
  };
}

Spezifikationen

Specification
Indexed Database API 3.0
# ref-for-dom-idbindex-openkeycursor①

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch