عرض مصدر JavaScript/Spread Operator

<noinclude>{{DISPLAYTITLE:معامل النشر Spread في JavaScript}}</noinclude>
معامل النشر ('''spread operator''') يسمح للكائنات التي يمكن المرور على عناصرها -مثل تعابير المصفوفات أو السلاسل النصية (أي أنها iterable)- أن توسَّع في الأماكن التي تتوقع JavaScript وجود صفر وسيط أو أكثر (عند استدعاء الدوال) أو صفر عنصر أو أكثر (في المصفوفات)، أو نشر كائن في الأماكن التي تتوقع JavaScript وجود صفر زوج أو أكثر من المفاتيح والقيم المرتبطة بها (عند تعريف الكائنات).
==البنية العامة==
عند استدعاء الدوال:<syntaxhighlight lang="javascript">
myFunction(...iterableObj);

</syntaxhighlight>في المصفوفات أو السلاسل النصية:<syntaxhighlight lang="javascript">
[...iterableObj, '4', 'five', 6];

</syntaxhighlight>عند تعريف الكائنات (ميزة جديدة في EMCAScript، انظر قسم «<nowiki/>[[#مصادر ومواصفات|مصادر ومواصفات]]»):<syntaxhighlight lang="javascript">
let objClone = { ...obj };

</syntaxhighlight>

== أمثلة ==

=== استخدام معامل النشر عند استدعاء الدوال ===

==== الاستغناء عن استخدام الدالة <code>apply</code> ====
من الشائع استخدام الدالة <code>[[JavaScript/Function/apply|Function.prototype.apply]]</code> في الحالات حيث تريد استخدام عناصر مصفوفة ما كوسائط لتمريرها إلى دالة:<syntaxhighlight lang="javascript">
function myFunction(x, y, z) { }
var args = [0, 1, 2];
myFunction.apply(null, args);

</syntaxhighlight>أما عند استخدام معامل النشر، فيمكن أن تُكتَب الشيفرة السابقة كما يلي:<syntaxhighlight lang="javascript">
function myFunction(x, y, z) { }
var args = [0, 1, 2];
myFunction(...args);

</syntaxhighlight>لاحظ أنَّ بالإمكان استخدام معامل النشر مكان أيّ وسيط من قائمة الوسائط، ويمكن أن يُكرَّر استخدامه عدِّة مرات:<syntaxhighlight lang="javascript">
function myFunction(v, w, x, y, z) { }
var args = [0, 1];
myFunction(-1, ...args, 2, ...[3]);

</syntaxhighlight>

==== استخدام معامل النشر عند استدعاء الدوال البانية ====
عند استدعاء دالة بانية باستخدام المعامل <code>[[JavaScript/new|new]]</code> فمن غير الممكن استخدام مصفوفة والدالة <code>[[JavaScript/Function/apply|apply]]</code> مباشرةً (إذ إنَّ الدالة <code>[[JavaScript/Function/apply|apply]]</code> تجري عملية استدعاء <code><nowiki>[[Call]]</nowiki></code> وليس بناء <code><nowiki>[[Construct]]</nowiki></code>)، لكن يمكن استخدام مصفوفة مع دالة بانية بسهولة عبر معامل النشر:<syntaxhighlight lang="javascript">
var dateFields = [1970, 0, 1];  // 1 Jan 1970
var d = new Date(...dateFields);

</syntaxhighlight>أما لاستخدام مصفوفة كمعاملات لدالة بانية دون استخدام معامل النشر، فيمكنك فعل ذلك بطريقة غير مباشرة كما في المثال الآتي:<syntaxhighlight lang="javascript">
function applyAndNew(constructor, args) {
   function partial () {
      return constructor.apply(this, args);
   };
   if (typeof constructor.prototype === "object") {
      partial.prototype = Object.create(constructor.prototype);
   }
   return partial;
}


function myConstructor () {
   console.log("arguments.length: " + arguments.length);
   console.log(arguments);
   this.prop1="val1";
   this.prop2="val2";
};

var myArguments = ["hi", "how", "are", "you", "mr", null];
var myConstructorWithArguments = applyAndNew(myConstructor, myArguments);

console.log(new myConstructorWithArguments);
// (internal log of myConstructor):           arguments.length: 6
// (internal log of myConstructor):           ["hi", "how", "are", "you", "mr", null]
// (log of "new myConstructorWithArguments"): {prop1: "val1", prop2: "val2"}

</syntaxhighlight>

=== استخدام معامل النشر مع المصفوفات ===

==== استفادة قصوى من الشكل المختصر لتعريف المصفوفات ====
دون استخدام معامل النشر، لن نتمكن من استخدام الشكل المختصرة لتعريف مصفوفة جديدة تستخدم مصفوفةً أخرى كجزء منها، وسيصبح استخدام شيفرة مطوّلة أمرٌ لا بدّ منه ويجب استخدام مجموعة من دوال <code>[[JavaScript/Array/push|push]]</code> و <code>[[JavaScript/Array/splice|splice]]</code> و <code>[[JavaScript/Array/concat|concat]]</code> ...إلخ. لكن عند استخدام معامل النشر فسيصير شكل تعريف المصفوفة أقصر بكثير:<syntaxhighlight lang="javascript">
var parts = ['shoulders', 'knees']; 
var lyrics = ['head', ...parts, 'and', 'toes']; 
// ["head", "shoulders", "knees", "and", "toes"]

</syntaxhighlight>وكما عند استخدام معامل النشر في قائمة وسائط الدالة، يمكن استخدام المعامل <code>...</code> في أيّ مكان في الشكل المختصر لتعريف المصفوفات ويمكن تكراره أكثر من مرة.

==== نسخ مصفوفة ====
لاحظ كيف سيؤدي استخدام معامل النشر إلى نسخ محتويات المصفوفة <code>arr</code> إلى <code>arr2</code>، وعند تغيير المصفوفة <code>arr2</code> فلن تتأثر المصفوفة الأصلية <code>arr</code>:<syntaxhighlight lang="javascript">
var arr = [1, 2, 3];
var arr2 = [...arr];
arr2.push(4); 

// arr2 [1, 2, 3, 4]
// arr ستبقى على حالها

</syntaxhighlight>لاحظ أنَّ معامل النشر لن ينسخ إلا مستوى واحد من المصفوفات، أي أنَّه ليس مناسبًا لنسخ المصفوفات متعددة الأبعاد كما يبيّن المثال الآتي، الذي سيتتأثر فيه المصفوفة <code>a</code> عند تغيير المصفوفة <code>b</code>:<syntaxhighlight lang="javascript">
var a = [[1], [2], [3]];
var b = [...a];
b.shift().shift(); // 1
// a: [[], [2], [3]]

</syntaxhighlight>

==== طريقة أفضل لجمع المصفوفات لبعضها بعضًا ====
تُستخدَم الدالة <code>[[JavaScript/Array/concat|concat]]</code> عادةً لإضافة مصفوفة ما إلى نهاية مصفوفة أخرى، ويمكن فعل ذلك دون معامل النشر كما في المثال الآتي الذي أضفنا فيه جميع عناصر المصفوفة <code>arr2</code> إلى نهاية المصفوفة <code>arr1</code>:<syntaxhighlight lang="javascript">
var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];

arr1 = arr1.concat(arr2);

</syntaxhighlight>يمكننا فعل ذلك باستخدام معامل النشر:<syntaxhighlight lang="javascript">
var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];

arr1 = [...arr1, ...arr2];

</syntaxhighlight>تُستخدَم الدالة <code>[[JavaScript/Array/unshift|unshift]]</code> عادةً لإضافة قيم مصفوفة ما إلى بداية مصفوفة أخرى:<syntaxhighlight lang="javascript">
var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];

Array.prototype.unshift.apply(arr1, arr2) // arr1: [3, 4, 5, 0, 1, 2]

</syntaxhighlight>أما مع استخدام معامل النشر، فسيُبسَّط المثال السابق كثيرًا:<syntaxhighlight lang="javascript">
var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];

arr1 = [...arr2, ...arr1]; // arr1: [3, 4, 5, 0, 1, 2]

</syntaxhighlight>

=== استخدام معامل النشر مع الكائنات ===
أضاف اقتراح Rest/Spread Properties for ECMAScript استخدام معامل النشر عند [[JavaScript/Object Initializer|تعريف الكائنات]]، حيث سينسخ الخاصيات القابلة للإحصاء (enumerable properties) من أحد الكائنات إلى الكائن الآخر.

أصبح بإمكاننا القيام بعملية النسخ السطحي (shallow cloning، أي باستثناء كائن <code>prototype</code>) أو دمج كائنين بطريقة أقصر من استخدام الدالة <code>[[JavaScript/Object/assign|Object.assign()‎]]</code>:<syntaxhighlight lang="javascript">
var obj1 = { foo: 'bar', x: 42 };
var obj2 = { foo: 'baz', y: 13 };

var clonedObj = { ...obj1 };
// Object { foo: "bar", x: 42 }

var mergedObj = { ...obj1, ...obj2 };
// Object { foo: "baz", x: 42, y: 13 }

</syntaxhighlight>

=== يُستخدَم معامل النشر لكائنات iterable فقط ===
لا يمكن أن يُطبَّق معامل النشر إلى على كائنات iterable فقط (باستثناء عملية نشر كائن ضمن كائن آخر):<syntaxhighlight lang="javascript">
var obj = {'key1': 'value1'};
var array = [...obj]; // TypeError: obj is not iterable

</syntaxhighlight>

=== معامل النشر مع قيم كثيرة ===
عند استخدام معامل النشر عند استدعاء الدوال، فضع في ذهنك إمكانية تجاوز العدد الأقصى للوسائط في محرِّك JavaScript؛ راجع صفحة الدالة <code>[[JavaScript/Function/apply|apply]]</code> لمزيدٍ من التفاصيل.

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم في المصفوفات
|46
|16
|غير مدعومة
|37
|8
|-
!الدعم في الدوال
|46
|27
|غير مدعومة
|37
|8
|-
!الدعم في الكائنات
|60
|55
|غير مدعومة
|؟
|غير مدعومة
|}
على النقيض من متصفح IE، يدعم متصفح Edge معامل النشر في المصفوفات والدوال.

== مصادر ومواصفات ==
* مسودة [https://github.com/tc39/proposal-object-rest-spread Rest/Spread Properties for ECMAScript] (في المرحلة الثالثة).
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-array-initializer ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-array-initializer ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Operator|{{SUBPAGENAME}}]]