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 bestimmten Datensatz in einer Datenbank oder fügt einen neuen Datensatz hinzu, wenn der angegebene Eintrag 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 Objekt-Store. Dies dient dem Hinzufügen neuer oder dem Aktualisieren vorhandener Datensätze in einem Objekt-Store, wenn der Modus der Transaktion readwrite ist. Wenn der Datensatz erfolgreich gespeichert wurde, wird ein Erfolgsevent auf dem zurückgegebenen Anforderungsobjekt ausgelöst, wobei das result auf den Schlüssel des gespeicherten Datensatzes gesetzt ist und die transaction auf die Transaktion gesetzt ist, in der dieser Objekt-Store geöffnet ist.

Die put-Methode ist eine Update- oder Insert-Methode. Sehen Sie sich die IDBObjectStore.add-Methode für eine Nur-Insert-Methode an.

Beachten Sie, dass, wenn Sie einen IDBCursor auf den Datensatz haben, den Sie aktualisieren möchten, es vorzuziehen ist, ihn mit IDBCursor.update() zu aktualisieren, anstatt IDBObjectStore.put() zu verwenden. Auf diese Weise wird deutlich, dass ein vorhandener Datensatz aktualisiert wird, anstatt dass ein neuer Datensatz eingefügt wird.

Syntax

js
put(item)
put(item, key)

Parameter

item

Der Eintrag, den 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, auf dem nachfolgende Ereignisse im Zusammenhang mit dieser Operation ausgelöst werden.

Wenn die Operation erfolgreich ist, ist der Wert der result-Eigenschaft der Anforderung der Schlüssel für den neuen oder aktualisierten Datensatz.

Ausnahmen

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

ReadOnlyError DOMException

Wird ausgelöst, wenn die mit dieser Operation verbundene Transaktion im Nur-Lese-Modus ist.

TransactionInactiveError DOMException

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

DataError DOMException

Wird ausgelöst, wenn eine der folgenden Bedingungen zutrifft:

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

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

DataCloneError DOMException

Wird ausgelöst, wenn die zu speichernden Daten nicht durch den internen strukturierten Klonalgorithmus geklont werden konnten.

Beispiele

Das folgende Beispiel fordert einen bestimmten Datensatz-Titel an; wenn diese Anforderung erfolgreich ist, ruft die onsuccess-Funktion den zugehörigen Datensatz aus dem IDBObjectStore ab (verfügbar gemacht als objectStoreTitleRequest.result), aktualisiert eine Eigenschaft des Datensatzes und fügt dann den aktualisierten Datensatz in einer weiteren Anforderung mit put() zurück in den Objekt-Store ein. Für ein vollständig funktionierendes Beispiel sehen Sie sich unsere To-do Notifications-App an (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

BCD tables only load in the browser

Siehe auch