IDBObjectStore.put()
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.
La méthode put()
, rattachée à l'interface IDBObjectStore
, renvoie un objet IDBRequest
et, dans un autre thread, crée un clone structuré de la valeur puis enregistre ce clone dans le magasin d'objet. Cette méthode permet ainsi d'ajouter de nouveaux enregistrements ou de mettre à jour des enregistrements existants dans un magasin d'objet lorsque la transaction est en mode readwrite
(lecture-écriture)
Si l'enregistrement est stocké avec succès, un évènement de succès sera déclenché sur la requête renvoyée par la méthode. La propriété result
de cette requête contiendra la clé de l'enregistrement créé ou mis à jour. La propriété transaction
de cette requête sera la transaction dans laquelle le magasin d'objet est ouvert.
La méthode put()
permet d'ajouter ou de mettre à jour. Si on souhaite uniquement insérer, on utilisera plutôt IDBObjectStore.add
.
Note : Cette fonctionnalité est disponible via les Web Workers.
Syntaxe
var request = objectStore.put(monElement);
var request = objectStore.put(monElement, cleOptionnelle);
Paramètres
monElement
-
La valeur qu'on souhaite enregistrer.
cleOptionnelle
Facultatif-
La clé qu'on souhaite utiliser pour identifier l'enregistrement. Si cet argument est absent, la valeur par défaut sera
null
.
Valeur de retour
Un objet IDBRequest
qui recevra les évènements qui seront déclenchés suite à cette opération.
Exceptions
Cette méthode peut lever une de ces exceptions DOMException
:
Exception | Description |
---|---|
ReadOnlyError |
La transaction associée à l'opération est uniquement dans un mode de lecture seule. |
TransactionInactiveError |
La transaction rattachée à l'objet
IDBObjectStore est inactive.
|
DataError |
L'une de ces conditions est vérifiée :
|
InvalidStateError |
L'objet IDBObjectStore a été supprimé ou
déplacé.
|
DataCloneError |
Les données à enregistrer n'ont pas pu être clonées par l'algorithme interne. |
Exemples
Dans l'exemple suivant, on effectue une requête pour obtenir l'enregistrement correspondant à un titre donné. Lorsque cette requête est réussie, on récupère l'enregistrement via la fonction onsuccess
. Ensuite, on met à jour une des propriétés de l'enregistrement et on enregistre la valeur mise à jour dans le magasin d'objet avec une autre requête et put()
.
var title = "Walk dog";
// On ouvre une transaction
var objectStore = db
.transaction(["toDoList"], "readwrite")
.objectStore("toDoList");
// On obtient la liste to-do dont le titre correspond
var objectStoreTitleRequest = objectStore.get(title);
objectStoreTitleRequest.onsuccess = function () {
// On récupère les données de l'objet associé
// à l'enregistrement
var data = objectStoreTitleRequest.result;
// On met à jour la valeur de notified avec "yes"
data.notified = "yes";
// On crée une autre requête pour appliquer cette
// mise à jour en base de données
var updateTitleRequest = objectStore.put(data);
// On imprime la transaction à l'origine
// de la requête
console.log(
"La transaction originelle est " + updateTitleRequest.transaction,
);
// Lorsque cette nouvelle requête a réussi. On affiche
// les données grâce à la fonction displayData()
updateTitleRequest.onsuccess = function () {
displayData();
};
};
Spécifications
Specification |
---|
Indexed Database API 3.0 # ref-for-dom-idbobjectstore-put① |
Compatibilité des navigateurs
BCD tables only load in the browser
Voir aussi
- Utiliser IndexedDB
- Initier une connexion :
IDBDatabase
- Utiliser les transactions :
IDBTransaction
- Définir un intervalle de clés :
IDBKeyRange
- Récupérer et modifier les données :
IDBObjectStore
- Utiliser les curseurs
IDBCursor
- Exemple de référence : To-do Notifications (exemple live).