IDBObjectStore: put() 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 put()-Methode der IDBObjectStore-Schnittstelle aktualisiert einen vorhandenen Datensatz in einer Datenbank oder fügt einen neuen Datensatz ein, wenn das angegebene Element noch nicht existiert.

Sie gibt ein IDBRequest-Objekt zurück und erstellt in einem separaten Thread einen strukturierten Klon des Wertes und speichert den geklonten Wert im Object Store. Dies dient dazu, neue Datensätze hinzuzufügen oder vorhandene Datensätze in einem Object Store zu aktualisieren, wenn der Modus der Transaktion readwrite ist. Wenn der Datensatz erfolgreich gespeichert wird, wird ein Erfolgsevent auf dem zurückgegebenen Anfrageobjekt ausgelöst, wobei das result auf den Schlüssel des gespeicherten Datensatzes gesetzt wird und die transaction auf die Transaktion, in der dieser Object Store geöffnet ist.

Die put-Methode ist eine Update- oder Insert-Methode. Siehe die IDBObjectStore.add-Methode für eine Insert-only-Methode.

Bedenken Sie, dass, wenn Sie einen IDBCursor für den Datensatz haben, den Sie aktualisieren möchten, es vorzuziehen ist, diesen mit IDBCursor.update() zu aktualisieren, anstatt IDBObjectStore.put() zu verwenden. Dies macht deutlich, dass ein vorhandener Datensatz aktualisiert wird, anstatt einen neuen Datensatz einzufügen.

Syntax

js
put(item)
put(item, key)

Parameter

item

Das Element, das Sie aktualisieren (oder einfügen) möchten.

key Optional

Der Primärschlüssel des Datensatzes, den Sie aktualisieren möchten (z. B. von IDBCursor.primaryKey).

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 der Schlüssel für den neuen oder aktualisierten Datensatz.

Ausnahmen

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

ReadOnlyError DOMException

Ausgelöst, wenn die Transaktion, die mit dieser Operation verbunden ist, im schreibgeschützten Modus ist.

TransactionInactiveError DOMException

Ausgelöst, wenn die Transaktion dieses IDBObjectStore inaktiv ist.

DataError DOMException

Ausgelöst, wenn eine der folgenden Bedingungen zutrifft:

  • Der Object Store verwendet Inline-Schlüssel oder hat einen Schlüsselgenerator und ein key-Parameter wurde angegeben.
  • Der Object Store verwendet Out-of-Line-Schlüssel und hat keinen Schlüsselgenerator, und es wurde kein key-Parameter angegeben.
  • Der Object Store verwendet Inline-Schlüssel, aber keinen Schlüsselgenerator, und der Schlüsselpfad des Object Stores liefert keinen gültigen Schlüssel.
  • Das key-Parameter wurde angegeben, enthält aber keinen gültigen Schlüssel.
InvalidStateError DOMException

Ausgelöst, wenn das IDBObjectStore gelöscht oder entfernt wurde.

DataCloneError DOMException

Ausgelöst, wenn die Daten, die gespeichert werden sollten, nicht durch den internen strukturierten Klonalgorithmus geklont werden konnten.

Beispiele

Das folgende Beispiel fordert einen gegebenen Datensatztitel an; wenn diese Anfrage erfolgreich ist, holt die onsuccess-Funktion den zugehörigen Datensatz aus dem IDBObjectStore (verfügbar gemacht durch objectStoreTitleRequest.result), aktualisiert eine Eigenschaft des Datensatzes und legt dann den aktualisierten Datensatz in einer weiteren Anfrage mit put() wieder in den Object Store zurück. Für ein vollständiges funktionierendes Beispiel siehe unsere To-do-Benachrichtigungen-App (Beispiel live ansehen).

js
const title = "Walk dog";

// Open up a transaction as usual
const objectStore = db
  .transaction(["toDoList"], "readwrite")
  .objectStore("toDoList");

// Get the to-do list object that has this title as its title
const objectStoreTitleRequest = objectStore.get(title);

objectStoreTitleRequest.onsuccess = () => {
  // Grab the data object returned as the result
  const data = objectStoreTitleRequest.result;

  // Update the notified value in the object to "yes"
  data.notified = "yes";

  // Create another request that inserts the item back into the database
  const updateTitleRequest = objectStore.put(data);

  // Log the transaction that originated this request
  console.log(
    `The transaction that originated this request is ${updateTitleRequest.transaction}`,
  );

  // When this new request succeeds, run the displayData() function again to update the display
  updateTitleRequest.onsuccess = () => {
    displayData();
  };
};

Spezifikationen

Specification
Indexed Database API 3.0
# ref-for-dom-idbobjectstore-put①

Browser-Kompatibilität

Siehe auch