IDBObjectStore.add()
La méthode add()
, rattachée à l'interface IDBObjectStore
, renvoie un objet IDBRequest
et, dans un thread séparé, crée un clone structurel de la valeur et stocke la valeur clonée dans le magasin d'objet. Cette méthode permet d'ajouter de nouveaux enregistrements dans un magasin d'objet.
Afin de déterminer si l'opération add
s'est effectuée correctement, on pourra écouter l'évènement complete
de la transaction et l'évènement success
de la requête IDBObjectStore.add
car la transaction peut échouer après le déclenchement de l'évènement success
. Autremnt dit, l'évènement success
est uniquement déclenché au moment où la transaction a été mise dans la file.
La méthode add
ne permet que d'insérer des objets. Si un enregistrement existe déjà dans le magasin d'objet pour la clé fournie en argument, un évènement ConstrainError
sera déclenché via l'objet IDBRequest
. Si on souhaite mettre à jour des enregistrements existants, on utilisera plutôt la méthode IDBObjectStore.put
.
Note : Cette fonctionnalité est disponible via les Web Workers.
Syntaxe
var request = objectStore.add(valeur, clé);
Paramètres
Valeur de retour
Un objet IDBRequest
qui émettra les différents évènements relatifs à l'opération.
Exceptions
Cette méthode peut lever une exception DOMException
ayant l'un des types suivants :
Exception | Description |
---|---|
ReadOnlyError |
La transaction associée à cette opération est en lecture seule. |
TransactionInactiveError |
La transaction pour cet objet IDBObjectStore
est inactive.
|
DataError |
Un des conditions suivantes est vérifiée :
|
InvalidStateError |
L'objet IDBObjectStore a été supprimé ou
déplacé.
|
DataCloneError |
La donnée qui devait être enregistrée n'a pas pu être clonée par l'algorithme de clonage interne. |
Exemples
Dans le fragment de code suivant, on ouvre une transaction en lecture/écriture vers la base de données et on ajoute des données au magasin d'objet grâce à la méthode add()
. On notera également les fonctions rattachées à la transaction qui sont utilisées comme gestionnaires d'évènement et qui permettent de savoir si la transaction a réussi ou échoué.
// On ouvre la base de données
var DBOpenRequest = window.indexedDB.open("toDoList", 4);
DBOpenRequest.onsuccess = function (event) {
note.innerHTML += "<li>Database initialisée.</li>";
// On enregistre le résultat dans la variable db
// afin de l'utiliser par la suite
var db = DBOpenRequest.result;
// On utilise la fonction addData() afin d'ajouter
// des données dans la base de données
addData();
};
function addData() {
// On crée un nouvel objet qu'on insèrera ensuite
// dans la base de données
var newItem = [
{
taskTitle: "Walk dog",
hours: 19,
minutes: 30,
day: 24,
month: "December",
year: 2013,
notified: "no",
},
];
// On ouvre une transaction en lecture/écriture
// afin d'ajouter les données
var transaction = db.transaction(["toDoList"], "readwrite");
// On indique si la transaction s'est déroulées
// sans problème
transaction.oncomplete = function (event) {
note.innerHTML += "<li>Transaction terminée : modification effectuée.</li>";
};
transaction.onerror = function (event) {
note.innerHTML +=
"<li>Ouverture de la transaction impossible : les objets dupliqués ne sont pas autorisés.</li>";
};
// On crée un magasin d'objets pour la transaction
var objectStore = transaction.objectStore("toDoList");
// On ajoute l'objet newItem dans le magasin d'objets
var objectStoreRequest = objectStore.add(newItem[0]);
objectStoreRequest.onsuccess = function (event) {
// On indique la réussite de l'insertion
note.innerHTML += "<li>Nouvel objet ajouté dans la base de données.</li>";
};
}
Note : Pour un exemple fonctionnel complet, voir notre application To-do (exemple).
Spécifications
Specification |
---|
Indexed Database API 3.0 # ref-for-dom-idbobjectstore-add① |
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).