IDBIndex: openCursor()-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 openCursor()-Methode der IDBIndex-Schnittstelle gibt ein IDBRequest-Objekt zurück und erstellt in einem separaten Thread einen Cursor über den angegebenen Schlüsselbereich.

Die Methode setzt die Position des Cursors auf den entsprechenden Datensatz basierend auf der angegebenen Richtung.

Wenn der Schlüsselbereich nicht angegeben ist oder null ist, umfasst der Bereich alle Datensätze.

Syntax

js
openCursor()
openCursor(range)
openCursor(range, direction)

Parameter

range Optional

Ein Schlüssel oder IDBKeyRange, der als Bereich des Cursors verwendet wird. Wenn nichts übergeben wird, wird standardmäßig ein Schlüsselbereich verwendet, der alle Datensätze in diesem Objektstore 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 im Zusammenhang mit dieser Operation ausgelöst werden.

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

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

Ausnahmen

Diese Methode kann eine DOMException 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 bereitgestellte 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 Objektstore, dann holen wir den Index lName aus einer einfachen Kontaktdatenbank. Wir öffnen dann einen einfachen Cursor auf dem Index mit openCursor() – das funktioniert genauso wie das direkte Öffnen eines Cursors auf einem ObjectStore mit IDBObjectStore.openCursor, außer dass die zurückgegebenen Datensätze basierend auf dem Index und nicht auf dem Primärschlüssel sortiert sind.

Schließlich iterieren wir durch jeden Datensatz und fügen die Daten in eine HTML-Tabelle ein. Für ein vollständiges funktionierendes Beispiel, siehe unser IndexedDB-Beispiele Demo-Repo (Sehen Sie sich das Beispiel live an).

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

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

  myIndex.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      for (const cell of [
        cursor.value.id,
        cursor.value.lName,
        cursor.value.fName,
        cursor.value.jTitle,
        cursor.value.company,
        cursor.value.eMail,
        cursor.value.phone,
        cursor.value.age,
      ]) {
        const tableCell = document.createElement("td");
        tableCell.textContent = cell;
        tableRow.appendChild(tableCell);
      }
      tableEntry.appendChild(tableRow);

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

Spezifikationen

Specification
Indexed Database API 3.0
# ref-for-dom-idbindex-opencursor②

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch