Rest parameters

Синтаксис rest parameters (остаточные параметры) позволяет функции принимать неопределенное количество аргументов в виде массива, предоставляя способ представления вариадных функций в JavaScript.

Попробуйте

function sum(...theArgs) {
  let total = 0;
  for (const arg of theArgs) {
    total += arg;
  }
  return total;
}

console.log(sum(1, 2, 3));
// Expected output: 6

console.log(sum(1, 2, 3, 4));
// Expected output: 10

Синтаксис

function f(a, b, ...theArgs) {
  // …
}

Существуют некоторые дополнительные ограничения синтаксиса:

• Определение функции может содержать только один rest parameter.
• Rest parameter должен быть последним параметром в определении функции.
• Запятые в конце не допускаются после rest parameter.
• Rest parameter не может иметь значение по умолчанию.

Описание

Последний параметр определения функции может быть предварен ... (три символа U+002E FULL STOP), что приведет к тому, что все оставшиеся (предоставленные пользователем) параметры будут помещены в объект Array.

function myFun(a, b, ...manyMoreArgs) {
  console.log("a", a);
  console.log("b", b);
  console.log("manyMoreArgs", manyMoreArgs);
}

myFun("one", "two", "three", "four", "five", "six");

// Console Output:
// a, one
// b, two
// manyMoreArgs, ["three", "four", "five", "six"]

Rest parameter может быть деструктурирован, что позволяет игнорировать определенные позиции параметров.

function ignoreFirst(...[, b, c]) {
  return b + c;
}

Однако следующие варианты являются синтаксическими ошибками:

function wrong1(...one, ...wrong) {}
function wrong2(...wrong, arg2, arg3) {}
function wrong3(...wrong,) {}
function wrong4(...wrong = []) {}

Rest parameter не учитывается при подсчете length свойства функции.

Разница между rest parameters и объектом arguments

Существует четыре основных отличия между rest parameters и объектом arguments:

• Объект arguments не является реальным массивом, в то время как rest parameters являются экземплярами Array, что означает, что такие методы, как sort(), map(), forEach() или pop(), могут применяться непосредственно к нему.
• Объект arguments имеет дополнительное (устаревшее) свойство callee.
• В нестрогой функции с обычными параметрами объект arguments синхронизирует свои индексы со значениями параметров. Массив rest parameter никогда не обновляет свое значение при переприсваивании именованных параметров.
• Rest parameter объединяет все *дополнительные* параметры в один массив, но не содержит никаких именованных аргументов, определенных *до* ...restParam. Объект arguments содержит все параметры — включая параметры в массиве ...restParam — объединенные в один объект, похожий на массив.

Примеры

Использование rest parameters

В этом примере первый аргумент сопоставляется с a, а второй — с b, поэтому эти именованные аргументы используются как обычно.

Однако третий аргумент, manyMoreArgs, будет массивом, содержащим третий, четвертый, пятый, шестой, ..., n-ный — столько аргументов, сколько укажет пользователь.

function myFun(a, b, ...manyMoreArgs) {
  console.log("a", a);
  console.log("b", b);
  console.log("manyMoreArgs", manyMoreArgs);
}

myFun("one", "two", "three", "four", "five", "six");

// a, "one"
// b, "two"
// manyMoreArgs, ["three", "four", "five", "six"] <-- an array

Ниже, даже если есть только одно значение, последний аргумент все равно помещается в массив.

// Using the same function definition from example above

myFun("one", "two", "three");

// a, "one"
// b, "two"
// manyMoreArgs, ["three"] <-- an array with just one value

Ниже третий аргумент не предоставлен, но manyMoreArgs по-прежнему является массивом (хоть и пустым).

// Using the same function definition from example above

myFun("one", "two");

// a, "one"
// b, "two"
// manyMoreArgs, [] <-- still an array

Ниже предоставлен только один аргумент, поэтому b получает значение по умолчанию undefined, но manyMoreArgs по-прежнему является пустым массивом.

// Using the same function definition from example above

myFun("one");

// a, "one"
// b, undefined
// manyMoreArgs, [] <-- still an array

Длина аргументов

Поскольку theArgs является массивом, количество его элементов определяется свойством length. Если единственным параметром функции является rest parameter, restParams.length будет равен arguments.length.

function fun1(...theArgs) {
  console.log(theArgs.length);
}

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

Использование rest parameters в сочетании с обычными параметрами

В следующем примере rest parameter используется для сбора всех параметров после первого параметра в массив. Каждое из значений параметров, собранных в массив, затем умножается на первый параметр, и массив возвращается:

function multiply(multiplier, ...theArgs) {
  return theArgs.map((element) => multiplier * element);
}

const arr = multiply(2, 15, 25, 42);
console.log(arr); // [30, 50, 84]

От arguments к массиву

Методы Array могут использоваться с rest parameters, но не с объектом arguments:

function sortRestArgs(...theArgs) {
  const sortedArgs = theArgs.sort();
  return sortedArgs;
}

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

function sortArguments() {
  const sortedArgs = arguments.sort();
  return sortedArgs; // this will never happen
}

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

Rest parameters были введены для уменьшения шаблонного кода, который обычно использовался для преобразования набора аргументов в массив.

До rest parameters arguments необходимо было преобразовать в обычный массив перед вызовом методов массива:

function fn(a, b) {
  const normalArray = Array.prototype.slice.call(arguments);
  // — or —
  const normalArray2 = [].slice.call(arguments);
  // — or —
  const normalArrayFrom = Array.from(arguments);

  const first = normalArray.shift(); // OK, gives the first argument
  const firstBad = arguments.shift(); // ERROR (arguments is not a normal array)
}

Теперь вы можете легко получить доступ к обычному массиву, используя rest parameter:

function fn(...args) {
  const normalArray = args;
  const first = normalArray.shift(); // OK, gives the first argument
}

Спецификации

Совместимость с браузерами

См. также

• Руководство по функциям
• Функции
• Синтаксис Spread (...)
• Параметры по умолчанию
• arguments
• Array