IDBObjectStore.add()

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 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

js
var request = objectStore.add(valeur, clé);

Paramètres

valeur

La valeur à ajouter au magasin.

clé

La clé qu'on souhaite utiliser pour identifier l'enregistrement. Si elle n'est pas indiquée, la valeur par défaut sera null.

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 :

  • Le magasin d'objet utilise des clés en ligne ou possède un générateur de clés et une clé a été fournie dans la fonction.
  • Le magasin d'objet utilise des clés hors lignes et et n'a pas de générateur de clés et aucune clé n'a été fournie dans la fonction.
  • Le magasin d'objet utilise des clés en ligne mais ne possède pas de générateur de clés et le chemin de clé utilisé par le magasin ne pointe pas vers une clé valide.
  • La clé a été fournie à la fonction mais ce paramètre n'est pas une clé valide.
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é.

js
// 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