IDBObjectStore: Methode openCursor()

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 IDBObjectStore-Schnittstelle gibt ein IDBRequest Objekt zurück und liefert in einem separaten Thread ein neues IDBCursorWithValue Objekt. Diese Methode wird zum Iterieren durch einen Object Store mit einem Cursor verwendet.

Um festzustellen, ob die Hinzufügeoperation erfolgreich abgeschlossen wurde, überwachen Sie das success-Ereignis des Ergebnisses.

Syntax

js
openCursor()
openCursor(query)
openCursor(query, direction)

Parameter

query Optional

Ein Schlüssel oder ein IDBKeyRange, der abgefragt werden soll. Wenn ein einzelner gültiger Schlüssel übergeben wird, ist das Standardverhalten ein Bereich, der nur diesen Schlüssel enthält. Wenn nichts übergeben wird, ist das Standardverhalten ein Schlüsselbereich, der alle Datensätze in diesem Object Store auswählt.

direction Optional

Ein String, der dem Cursor mitteilt, in welche Richtung er navigieren soll. Der Standardwert ist next. Gültige Werte sind:

next

Der Cursor wird am Anfang des Stores geöffnet; dann gibt der Cursor alle Datensätze, einschließlich Duplikaten, in aufsteigender Reihenfolge der Schlüssel zurück.

nextunique

Der Cursor wird am Anfang des Stores geöffnet; dann gibt der Cursor alle Datensätze, die keine Duplikate sind, in aufsteigender Reihenfolge der Schlüssel zurück.

prev

Der Cursor wird am Ende des Stores geöffnet; dann gibt der Cursor alle Datensätze, einschließlich Duplikaten, in absteigender Reihenfolge der Schlüssel zurück.

prevunique

Der Cursor wird am Ende des Stores geöffnet; dann gibt der Cursor alle Datensätze, die keine Duplikate sind, in absteigender Reihenfolge der Schlüssel zurück.

Rückgabewert

Ein IDBRequest Objekt, bei dem nachfolgende Ereignisse im Zusammenhang mit dieser Operation ausgelöst werden.

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

  • ein IDBCursorWithValue Objekt, das auf den ersten Datensatz verweist, der der angegebenen Abfrage entspricht
  • null, wenn keine übereinstimmenden Datensätze gefunden wurden.

Ausnahmen

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

InvalidStateError DOMException

Wird ausgelöst, wenn dieser IDBObjectStore oder IDBIndex gelöscht wurde.

TransactionInactiveError DOMException

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

DataError DOMException

Wird ausgelöst, wenn der angegebene Schlüssel oder Schlüsselbereich ungültig ist.

Beispiele

In diesem einfachen Fragment erstellen wir eine Transaktion, rufen einen Object Store ab und verwenden dann einen Cursor, um durch alle Datensätze im Object Store zu iterieren:

js
const transaction = db.transaction("name", "readonly");
const objectStore = transaction.objectStore("name");
const request = objectStore.openCursor();
request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    // cursor.value contains the current record being iterated through
    // this is where you'd do something with the result
    cursor.continue();
  } else {
    // no more results
  }
};

Spezifikationen

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

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch