عرض مصدر JavaScript/Object/assign

<noinclude>{{DISPLAYTITLE:<code>Object.assign()‎</code>}}</noinclude>
الدالة <code>Object.assign()‎</code> تُستخدَم لنسخ قيمة جميع الخاصيات القابلة للإحصاء التابعة للكائن مباشرة (enumerable own properties) من كائنٍ مصدريٍ (source object) أو أكثر، وستُعيد الكائن الهدف (target object).
==البنية العامة==
<syntaxhighlight lang="javascript">
Object.assign(target, ...sources)

</syntaxhighlight>

=== <code>target</code> ===
الكائن الهدف.

=== <code>sources</code> ===
الكائنات المصدرية.

=== القيمة المعادة ===
الكائن الهدف.

== الوصف ==
سيستعاض عن الخاصيات في الكائن الهدف بالخاصيات الموجودة في الكائنات المصدرية إن كانت تحمل المفتاح نفسه؛ وستُستخدَم قيمة الخاصيات الموجودة الكائنات المصدرية الأخيرة إذا وجدت خاصيات لها نفس المفتاح في الكائنات المصدرية الأولى. 

لا تنسخ الدالة <code>Object.assign()‎</code> إلا الخاصيات القابلة للإحصاء والتي يملكها الكائن (enumerable own properties) من الكائن المصدري إلى الكائن الهدف، وستستخدم <code><nowiki>[[Get]]</nowiki></code> على المصدر و <code><nowiki>[[Set]]</nowiki></code> على الهدف، وبالتالي ستستدعى دوال [[JavaScript/set|setter]] و [[JavaScript/get|getter]]، وبالتالي ستُسنِد الخاصيات (assign) ولن تنسخها أو تُنشِئ خاصيات جديدة، وقد يكون ذلك غير مناسبٍ لغرض دمج الخاصيات الجديدة في سلسلة prototype إذا كان الكائنات المصدرية تحتوي على دوال [[JavaScript/get|getter]]؛ فلنسخ تعريف الخاصيات إلى خاصية <code>prototype</code> فيجب استخدام الدالتين <code>[[JavaScript/Object/getOwnPropertyDescriptor|Object.getOwnPropertyDescriptor()]]</code>‎ و <code>[[JavaScript/Object/defineProperty|Object.defineProperty()]]</code>‎ بدلًا منها. 

لاحظ أنَّ الخاصيات ذات المفاتيح من النوع <code>[[JavaScript/String|String]]</code> و <code>[[JavaScript/Symbol|Symbol]]</code> ستُنسَخ إلى الكائن الهدف عند استخدام هذه الدالة. 

في حال حدوث خطأ (مثلًا: إذا كانت الخاصية غير قابلة للكتابة) فسيرمى الخطأ <code>[[JavaScript/TypeError|TypeError]]</code>، وسيتغيّر الكائن الهدف <code>target</code> إذا أُضيفَت أيّة خاصيات قبل وقوع الخطأ. 

لاحظ أنَّ الدالة <code>Object.assign()‎</code> لن ترمي خطأً إذا كانت إحدى القيم المصدرية هي <code>[[JavaScript/null|null]]</code> أو <code>[[JavaScript/undefined|undefined]]</code>. 

== أمثلة ==

=== إنشاء نسخة من كائن ===
<syntaxhighlight lang="javascript">
var obj = { a: 1 };
var copy = Object.assign({}, obj);
console.log(copy); // { a: 1 }
</syntaxhighlight>

=== النسخ العميق للكائنات ===
إذا أردنا نسخ الخاصيات نسخًا عميقًا (deep clone)، فيجب علينا استخدام بدائل أخرى لأنَّ الدالة <code>Object.assign()‎</code> ستنسخ قيم الكائنات فقط، ولو كانت القيمة هي مرجعية إلى كائنٍ آخر، فلن تُنسَخ إلا المرجعية إلى ذاك الكائن.<syntaxhighlight lang="javascript">
function test() {
  'use strict';

  let obj1 = { a: 0 , b: { c: 0}};
  let obj2 = Object.assign({}, obj1);
  console.log(JSON.stringify(obj2)); // { a: 0, b: { c: 0}}
  
  obj1.a = 1;
  console.log(JSON.stringify(obj1)); // { a: 1, b: { c: 0}}
  console.log(JSON.stringify(obj2)); // { a: 0, b: { c: 0}}
  
  obj2.a = 2;
  console.log(JSON.stringify(obj1)); // { a: 1, b: { c: 0}}
  console.log(JSON.stringify(obj2)); // { a: 2, b: { c: 0}}
  
  obj2.b.c = 3;
  console.log(JSON.stringify(obj1)); // { a: 1, b: { c: 3}}
  console.log(JSON.stringify(obj2)); // { a: 2, b: { c: 3}}
  
  // نسخ عميق
  obj1 = { a: 0 , b: { c: 0}};
  let obj3 = JSON.parse(JSON.stringify(obj1));
  obj1.a = 4;
  obj1.b.c = 4;
  console.log(JSON.stringify(obj3)); // { a: 0, b: { c: 0}}
}

test();
</syntaxhighlight>

=== دمج الكائنات ===
لاحظ أنَّ الكائن الهدف سيتغيّر في المثال الآتي:<syntaxhighlight lang="javascript">
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 } هذا هو الكائن الهدف

</syntaxhighlight>

=== دمج الكائنات التي تملك نفس الخاصيات ===
إذا كانت هنالك خاصيةٌ موجودةٌ في أكثر من كائن، فستستخدم قيمة آخر نسخة منها بين الكائنات المصدرية؛ فلاحظ كيف ستكون قيمة الخاصية <code>b</code> تساوي <code>2</code> في المثال الآتي، وهي آتيةٌ من الكائن <code>o2</code>، بينما قيمة الخاصية <code>c</code> ستساوي <code>3</code> لأنها موجودة في الكائن <code>o3</code>:<syntaxhighlight lang="javascript">
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 }

</syntaxhighlight>

=== نسخ الخاصيات غير القابلة للإحصاء أو الموجودة في سلسلة prototype ===
سنستخدم في المثال الآتي الدالة <code>[[JavaScript/Object/create|Object.create()]]‎</code> لإنشاء الكائن <code>obj</code> مع تحديد الكائن الذي يملك الخاصية <code>foo</code> كقيمة للخاصية prototype، وسنُعرِّف الخاصية <code>bar</code> على أنها خاصية غير قابلة للإحصاء (non-enumerable)، بينما الخاصية <code>baz</code> هي خاصيةٌ تابعةٌ للكائن <code>obj</code> وقابلةٌ للإحصاء؛ لاحظ ما هي الخاصيات التي سيمتلكها الكائن <code>copy</code> المنسوخ من الكائن <code>obj</code>:<syntaxhighlight lang="javascript">
var obj = Object.create({ foo: 1 }, { // هذه الخاصية موجودة في سلسلة prototype
  bar: {
    value: 2  // هذه الخاصية غير قابلة للإحصاء
  },
  baz: {
    value: 3,
    enumerable: true  // هذه الخاصية تابعة للكائن وقابلة للإحصاء
  }
});

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

</syntaxhighlight>

=== ستحوّل القيم الأولية إلى كائنات ===
لاحظ كيف سيتم تجاهل القيمتين <code>[[JavaScript/null|null]]</code> و <code>[[JavaScript/undefined|undefined]]</code>، ولن توجد خاصيات قابلة للإحصاء إلا لكائنات السلاسل النصية:<syntaxhighlight lang="javascript">
var v1 = 'abc';
var v2 = true;
var v3 = 10;
var v4 = Symbol('foo');

var obj = Object.assign({}, v1, null, v2, undefined, v3, v4); 

console.log(obj); // { "0": "a", "1": "b", "2": "c" }

</syntaxhighlight>

=== ستقاطع الاستثناءات عملية النسخ ===
سنُعرِّف في المثال الآتي الخاصية <code>foo</code> للكائن <code>target</code> عبر الدالة <code>[[JavaScript/Object/defineProperty|Object.defineProperty()]]‎</code> لجعلها قابلةً للقراءة فقط، ثم سنحاول نسخ عدِّة كائنات باستخدام الدالة <code>Object.assign()‎</code>؛ وأحد الكائنات المصدرية فيه خاصية باسم <code>foo</code>، وسيرمى الخطأ <code>[[JavaScript/TypeError|TypeError]]</code> عند محاولة نسخ قيمتها إلى الكائن الهدف:<syntaxhighlight lang="javascript">
var target = Object.defineProperty({}, 'foo', {
  value: 1,
  writable: false
}); // هذه الخاصية غير قابلة للكتابة

Object.assign(target, { bar: 2 }, { foo2: 3, foo: 3, foo3: 3 }, { baz: 4 });
// TypeError: "foo" is read-only
// سيرمى الاستثناء عند محاولة إسناد الخاصية target.foo

console.log(target.bar);  // 2, نُسِخَ أوّل كائن مصدري بنجاح
console.log(target.foo2); // 3, أول خاصية من خاصيات الكائن الثاني نُسِخَت بنجاح
console.log(target.foo);  // 1, رُمِيَ الاستثناء هنا
console.log(target.foo3); // undefined, توقفت عملية النسخ
console.log(target.baz);  // undefined, توقفت عملية النسخ

</syntaxhighlight>

=== نسخ دوال <code>getter</code> ===
سنُعرِّف دالة [[JavaScript/get|getter]] في الكائن <code>obj</code>، ثم سننسخه عبر الدالة <code>Object.assign()‎</code> التي ستأخذ ناتج دالة getter وتضعه في الكائن الهدف:<syntaxhighlight lang="javascript">
var obj = {
  foo: 1,
  get bar() {
    return 2;
  }
};

var copy = Object.assign({}, obj); 
console.log(copy); 
// { foo: 1, bar: 2 }
</syntaxhighlight>هذه دالة ستنسخ دوال [[JavaScript/get|getter]] و [[JavaScript/set|setter]] كما هي:<syntaxhighlight lang="javascript">
function completeAssign(target, ...sources) {
  sources.forEach(source => {
    let descriptors = Object.keys(source).reduce((descriptors, key) => {
      descriptors[key] = Object.getOwnPropertyDescriptor(source, key);
      return descriptors;
    }, {});

    Object.getOwnPropertySymbols(source).forEach(sym => {
      let descriptor = Object.getOwnPropertyDescriptor(source, sym);
      if (descriptor.enumerable) {
        descriptors[sym] = descriptor;
      }
    });
    Object.defineProperties(target, descriptors);
  });
  return target;
}


var copy = completeAssign({}, obj);
console.log(copy);
// { foo:1, get bar() { return 2 } }
</syntaxhighlight>

== تعويض نقص دعم المتصفحات ==
الشيفرة الآتية تُعوِّض نقص دعم المتصفحات للدالة <code>Object.assign()‎</code>، لاحظ أنَّ هذه الشيفرة لا تدعم الخاصيات المرتبطة مع مفاتيح من النوع <code>[[JavaScript/Symbol|Symbol]]</code>، لكن معيار ES5 ليس فيه رموز (symbols) من الأساس:<syntaxhighlight lang="javascript">
if (typeof Object.assign != 'function') {
  // Must be writable: true, enumerable: false, configurable: true
  Object.defineProperty(Object, "assign", {
    value: function assign(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;
    },
    writable: true,
    configurable: true
  });
}

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|45
|34
|غير مدعومة
|32
|9
|}

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-object.assign ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-object.assign ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Object|{{SUBPAGENAME}}]]