Object.assign()

La méthode Object.assign() est utilisée afin de copier les valeurs de toutes les propriétés directes (non héritées) d'un objet qui sont énumérables sur un autre objet cible. Cette méthode renvoie l'objet cible.

Syntaxe

Object.assign(cible, ...sources)

Paramètres

cible
L'objet cible.
sources
Le(s) objet(s) source(s).

Valeur de retour

L'objet cible, éventuellement modifié, est renvoyé.

Description

La méthode Object.assign permet de ne copier que les propriétés énumérables et propres (les propriétés qui ne sont pas héritées) depuis un objet source vers un objet cible. Elle utilise [[Get]] sur l'objet source et [[Set]] sur l'objet cible, ainsi, elle déclenchera les accesseurs/mutateurs. De cette façon, elle affecte les propriétés plutôt que de juste les copier ou d'en définir de nouvelles. Aussi, il est déconseillé d'utiliser cette méthode si on souhaite uniquement fusionner de nouvelles propriétés dans un prototype si un des objets sources contient des accesseurs. Pour uniquement copier les définitions des propriétés (y compris leur énumérabilité) dans des prototypes, on utilisera plutôt Object.getOwnPropertyDescriptor() et Object.defineProperty().

Les propriétés String et Symbol sont copiées. Les propriétés de l'objet cible sont surchargées par celles de l'objet source si elles ont la même clé.

En cas d'erreur, si une propriété n'est pas accessible en écriture par exemple, une exception TypeError sera levée mais l'affectation continue et l'exception est lancée à la fin.

Object.assign ne donnera pas d'erreur si on fournit les valeurs null ou undefined pour la valeur source.

Exemples

Cloner un objet

var obj = { a: 1 };
var copie = Object.assign({}, obj);
console.log(copie); // {a: 1}

Note : Attention, pour un clone réel (deep clone), il faudra utiliser d'autres méthodes car Object.assign() ne copie que les références des propriétés depuis l'objet source, il ne recopie pas intégralement une nouvelle propriété.

Fusionner des objets

var o1 = { a: 1 };
var o2 = { b: 2 };
var o3 = { c: 3 };

var obj = Object.assign(o1, o2, o3);
console.log(obj); // { a: 1, b: 2, c: 3 }
console.log(o1);  // { a: 1, b: 2, c: 3 }, l'objet cible est aussi modifié

Fusionner des objets partageant des propriétés

var o1 = { a: 1, b: 1, c: 1 };
var o2 = { b: 2, c: 2 };
var o3 = { c: 3 };

var obj = Object.assign({}, o1, o2, o3);
console.log(obj); // { a: 1, b: 2, c: 3 }

Les propriétés communes sont surchargées selon l'ordre des paramètres.

Copier des propriétés symboliques

var o1 = { a: 1 };
var o2 = { [Symbol('toto')]: 2 };

var obj = Object.assign({}, o1, o2);
console.log(obj); // { a: 1, [Symbol("toto")]: 2 }
// Attention : dans Firefox le symbole n'est pas affiché
// en raison du bug 1207182
console.log(Object.getOwnPropertySymbols(obj)); // [Symbol(toto)]

Les propriétés héritées et les propriétés non-énumérables ne peuvent être copiées

var obj = Object.create({ toto: 1 }, { // toto est héritée
  truc: {
    value: 2  // truc est non-enumerable (par défaut)
  },
  bidule: {
    value: 3,
    enumerable: true  // bidule est une propriété propre et énumérable
  }
});

var copie = Object.assign({}, obj);
console.log(copie); // { bidule: 3 }

Les types primitifs seront passés en objets

var v1 = 'abc';
var v2 = true;
var v3 = 10;
var v4 = Symbol('toto')

var obj = Object.assign({}, v1, null, v2, undefined, v3, v4); 
// Les valeurs primitives seront converties, null et undefined seront ignorés.
// Note : seules les chaînes peuvent avoir des propriétés énumérables.
console.log(obj); // { "0": "a", "1": "b", "2": "c" }

Les exceptions interrompent la copie

var target = Object.defineProperty({}, 'toto', {
  value: 1,
  writable: false
}); // target.toto est en lecture seule

Object.assign(target, { truc: 2 }, { toto2: 3, toto: 3, toto3: 3 }, { bidule: 4 });
// TypeError: "toto" est en lecture seule
// L'exception est levée lorsqu'on affecte target.toto

console.log(target.truc);  // 2, le premier objet source est bien copié
console.log(target.toto2); // 3, la première propriété du deuxième objet source est bien copiée
console.log(target.toto);  // 1, on a une exception ici
console.log(target.toto3); // undefined, assign est terminé toto3 ne sera pas copié
console.log(target.bidule);// undefined, le troisième objet source ne sera pas copié non plus.

Copier des accesseurs

var obj = {
  toto: 1,
  get truc() {
    return 2;
  }
};

var copie = Object.assign({}, obj);
console.log(copie);
// { toto: 1, truc: 2 }, la valeur de copie.truc 
// est la valeur renvoyée par l'accesseur d'obj.truc.

// Voici une fonction qui copie les descripteurs
// dans leur intégralité
function completeAssign(target, ...sources) {
  sources.forEach(source => {
    let descriptors = Object.keys(source).reduce((descriptors, key) => {
      descriptors[key] = Object.getOwnPropertyDescriptor(source, key);
      return descriptors;
    }, {});
    // Par défaut, Object.assign copie également
    // les symboles énumérables
    Object.getOwnPropertySymbols(source).forEach(sym => {
      let descriptor = Object.getOwnPropertyDescriptor(source, sym);
      if (descriptor.enumerable) {
        descriptors[sym] = descriptor;
      }
    });
    Object.defineProperties(target, descriptors);
  });
  return target;
}

var copie = completeAssign({}, obj);
console.log(copie);
// { toto:1, get truc() { return 2 } }

Prothèse d'émulation (polyfill)

Ce fragment de code pour l'émulation ne supporte pas l'utilisation de symboles car ES5 ne possède pas les symboles :

if (typeof Object.assign != 'function') {
  Object.assign = function (target, varArgs) { // .length of function is 2
    'use strict';
    if (target == null) { // TypeError if undefined or null
      throw new TypeError('Cannot convert undefined or null to object');
    }

    var to = Object(target);

    for (var index = 1; index < arguments.length; index++) {
      var nextSource = arguments[index];

      if (nextSource != null) { // Skip over if undefined or null
        for (var nextKey in nextSource) {
          // Avoid bugs when hasOwnProperty is shadowed
          if (Object.prototype.hasOwnProperty.call(nextSource, nextKey)) {
            to[nextKey] = nextSource[nextKey];
          }
        }
      }
    }
    return to;
  };
}

Spécifications

Spécification État Commentaires
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Object.assign' dans cette spécification.
Standard Définition initiale.
ECMAScript 2017 Draft (ECMA-262)
La définition de 'Object.assign' dans cette spécification.
Projet  

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Edge Opera Safari
Support simple 45 34 (34) Pas de support (Oui) 32 9
Fonctionnalité Android Chrome pour Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support simple Pas de support 45 34.0 (34) Pas de support Pas de support (Oui)

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, lespacedunmatin, Cobrand, naholyr
 Dernière mise à jour par : SphinxKnight,