عرض مصدر JavaScript/Rest Parameters

<noinclude>{{DISPLAYTITLE:معامل البقية Rest في JavaScript}}</noinclude>
يسمح معامل البقية (rest parameter) بتمثيل عدد غير مُحدِّد من الوسائط المُمرَّرة إلى دالةٍ ما كمصفوفة.

== البنية العامة ==
<syntaxhighlight lang="javascript">
function f(a, b, ...theArgs) {
  // ...
}
</syntaxhighlight>

== الوصف ==
إذا أُسبِقَ آخر معامل من معاملات الدالة بثلاث نقط <code>...</code> فسيصبح مصفوفةً التي تبدأ من <code>0</code> حتى <code>theArgs.length</code> التي تحمل قيم الوسائط التي مُرِّرَت إلى الدالة.

ففي الشيفرة الموجودة في القسم السابق، ستحمل المصفوفة <code>theArgs</code> قيمة الوسيط الثالث المُمرَّر إلى الدالة (لأنَّ أوّل وسيط سيرتبط بالمعامل <code>a</code>، وسيرتبط ثاني وسيط بالمعامل <code>b</code>) وكل ما يليه من الوسائط.

=== الفرق بين معامل البقية والكائن <code>arguments</code> ===
هنالك ثلاثة فروقات رئيسية بين معامل البقية (rest parameter) والكائن [[JavaScript/arguments|arguments]]:
* ستُسنَد الوسائط التي لم يعطَ لها اسم إلى المصفوفة التي يُشير إليها معامل البقية، بينما يحتوي الكائن <code>[[JavaScript/arguments|arguments]]</code> على جميع الوسائط المُمرَّرة إلى الدالة.
* الكائن <code>[[JavaScript/arguments|arguments]]</code> ليس مصفوفةً حقيقةً، لكن معامل البقية من نوع الكائنات <code>[[JavaScript/Array|Array]]</code>، لذا يمكن تطبيق الدوال <code>[[JavaScript/Array/sort|sort]]</code> و <code>[[JavaScript/Array/map|map]]</code> و <code>[[JavaScript/Array/forEach|forEach]]</code> و <code>[[JavaScript/Array/pop|pop]]</code> عليه مباشرةً.
* الكائن <code>argument</code> يملك خصائص تابعة له فقط (مثل الخاصية <code>callee</code>).

=== التحويل من استخدام الكائن <code>[[JavaScript/arguments|arguments]]</code> إلى معامل البقية ===
أُضيف معامل البقية لتقليل مقدار الشيفرة التي ليس لها حاجة والتي يجب استخدامها مع الكائن <code>[[JavaScript/arguments|arguments]]</code>:<syntaxhighlight lang="javascript">
// كنا نستخدم الشيفرة الآتية قبل معامل البقية
function f(a, b) {
  var args = Array.prototype.slice.call(arguments, f.length);

  // ...
}

// ما سبق يكافئ ما يلي

function f(a, b, ...args) {
  
}
</syntaxhighlight>

=== تفكيك قيم معامل البقية ===
يمكن تفكيك معامل البقية، وهذا يعني أنَّ بياناته ستُسنَد إلى متغيرات منفصلة، راجع صفحة [[JavaScript/Destructuring Assignment|الإسناد بالتفكيك]] لمزيدٍ من المعلومات.<syntaxhighlight lang="javascript">
function f(...[a, b, c]) {
  return a + b + c;
}

f(1)          // NaN (b, c غير معرفة)
f(1, 2, 3)    // 6
f(1, 2, 3, 4) // 6 (لن يُفكَّك المعامل الرابع)

</syntaxhighlight>

== أمثلة ==
لمّا كان المعامل <code>theArgs</code> هو مصفوفة، فيمكن الحصول على عدد العناصر الموجودة فيه باستخدام الخاصية <code>length</code>:<syntaxhighlight lang="javascript">
function fun1(...theArgs) {
  console.log(theArgs.length);
}

fun1();  // 0
fun1(5); // 1
fun1(5, 6, 7); // 3

</syntaxhighlight>استخدمنا معامل البقية في المثال الآتي لجمع جميع الوسائط المُمرَّرة إلى الدالة -بعد الوسيط الأول- في مصفوفة، ثم ضُرِبَ كلُّ واحدٍ منها بقيمة الوسيط الأوّل ثم ستُعاد المصفوفة الناتجة:<syntaxhighlight lang="javascript">
function multiply(multiplier, ...theArgs) {
  return theArgs.map(function(element) {
    return multiplier * element;
  });
}

var arr = multiply(2, 1, 2, 3); 
console.log(arr); // [2, 4, 6]

</syntaxhighlight>المثال الآتي يُظهِر أنَّ الدوال التابعة للكائن <code>[[JavaScript/Array|Array]]</code> يمكن استخدامها على معامل البقية، لكن لا يمكن استخدامها على الكائن <code>[[JavaScript/arguments|arguments]]</code>:<syntaxhighlight lang="javascript">
function sortRestArgs(...theArgs) {
  var sortedArgs = theArgs.sort();
  return sortedArgs;
}

console.log(sortRestArgs(5, 3, 7, 1)); // 1, 3, 5, 7

function sortArguments() {
  var sortedArgs = arguments.sort(); 
  return sortedArgs; // لن يُنفَّذ ذلك
}


console.log(sortArguments(5, 3, 7, 1)); // TypeError (arguments.sort is not a function)

</syntaxhighlight>أما إذا أردنا استخدام دوال <code>[[JavaScript/Array|Array]]</code> على الكائن <code>[[JavaScript/arguments|arguments]]</code>، فيجب تحويله إلى مصفوفة حقيقية أولًا:<syntaxhighlight lang="javascript">
function sortArguments() {
  var args = Array.from(arguments);
  var sortedArgs = args.sort();
  return sortedArgs;
}
console.log(sortArguments(5, 3, 7, 1)); // 1, 3, 5, 7

</syntaxhighlight>

== <nowiki/>دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|47
|15
|غير مدعومة
|34
|10
|-
!الإسناد بالتفكيك
|49
|52
|غير مدعومة
|36
|؟
|}
على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة دعمًا أساسيًا (دون دعم الإسناد بالتفكيك) بدءًا من الإصدار 12.

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-function-definitions ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-function-definitions ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript]]
[[تصنيف:JavaScript Functions]]