O métodoapply() chama uma função com um dado valorthis earguments providos como uma array (ou um objeto parecido com um array).

Sintaxe

fun.apply(thisArg, [argsArray])

Parâmetros

thisArg

O valor dethis é fornecido para a chamada defun. Note que isso talvez não seja o valor real visto pelo método: se um método é uma função em códigonon-strict mode ,null eundefined serão substituidos com o objeto global, e os valores primitivos serão embalados.

argsArray

Um objeto parecido com um array (array-like), especificando os argumentos com os quaisfun deve ser chamado, ounull ouundefined se não houverem argumentos que possam ser passados para a função. Começando com ECMAScript5 esses argumentos podem ser um objeto genérico array-like ao invés de um array. Veja abaixo a informação decompatibilidade de browsers.

Descrição

Você pode atribuir um objetothis diferente quando chamar uma função existente.this refere-se ao objeto atual, o objeto da chamada. Comapply, você pode escrever um método apenas uma vez e então herdá-lo em outro objeto, sem ter que reescrever o método para o novo objeto.

apply é muito parecido comcall(), exceto pelo tipo de argumentos que ele suporta. Você pode usar um array de argumentos em vez de conjunto de parâmetros nomeados. Comapply, você pode usar um array literal, por exemplo,fun.apply(this, ['comer', 'bananas']), ou um objetoArray, por exemplofun.apply(this, new Array('comer', 'bananas')).

Você pode também usararguments para o parâmetroargsArray.argumentsé uma variável local de uma função. Ele pode ser utilizado para todos os argumentos não especificados do objeto chamado. Assim, você não tem que saber os argumentos do objeto chamado quando você usa o métodoapply. Você pode usararguments para passar todos os argumentos para o objeto da chamada. O objeto chamado fica então responsável por manipular os argumentos.

Desde a 5a versão do ECMAScript você pode utilizar qualquer tipo de objeto que é parecido com um array (array-like), então na prática isso significa que ele vai ter uma propriedadelength e propriedades inteiras no intervalor (0... length). Como um exemplo, você pode agora usar umNodeList ou um objeto personalizado como{ 'length': 2, '0': 'comer', '1': 'bananas' }.

Exemplos

Usandoapply para cadeia de construtores

Você pode usarapply para encadearconstrutores em um objeto, similar ao Java. No exemplo seguinte nós iremos criar um método deFunção global chamadoconstruct, que fará você capaz de usar um objeto parecido com um array com um construtor ao invés de uma lista de argumentos

Function.prototype.construct = function (aArgs) {  var oNew = Object.create(this.prototype);  this.apply(oNew, aArgs);  return oNew;};

Function.prototype.construct = function (aArgs) {  var fConstructor = this,    fNewConstr = function () {      fConstructor.apply(this, aArgs);    };  fNewConstr.prototype = fConstructor.prototype;  return new fNewConstr();};

Exemplo de uso:

function MyConstructor() {  for (var nProp = 0; nProp < arguments.length; nProp++) {    this["property" + nProp] = arguments[nProp];  }}var myArray = [4, "Hello world!", false];var myInstance = MyConstructor.construct(myArray);console.log(myInstance.property1); // logs 'Hello world!'console.log(myInstance instanceof MyConstructor); // logs 'true'console.log(myInstance.constructor); // logs 'MyConstructor'

Usandoapply e funções embutidas

A forma inteligente com queapply é utilizado permite à você usar funções nativas que de outra forma provavelmente teriam que ser escritas iterando sobre um array de valores. Aqui, como exemplo, iremos utilizarMath.max/Math.min para achar o valor máximo/mínimo value em um array.

/* número min/max em um array */var numbers = [5, 6, 2, 3, 7];/* utilizando Math.min/Math.max apply */var max = Math.max.apply(  null,  numbers,); /* Isso está prestes a ser igual a Math.max(numbers[0], ...)                                            ou Math.max(5, 6, ...) */var min = Math.min.apply(null, numbers);/* vs. algoritmo simples baseado em loop */((max = -Infinity), (min = +Infinity));for (var i = 0; i < numbers.length; i++) {  if (numbers[i] > max) {    max = numbers[i];  }  if (numbers[i] < min) {    min = numbers[i];  }}

Mas tome cuidado: ao utilizar oapply desta forma, você corre o risco de exceder o limite de argumentos do JavaScript. As consequências de fazer applying em uma função com muitos argumentos (pense em algo como dezenas de centenas de argumentos) varia de acordo com os engines (JavaScriptCore tem umlimite de argumentos de 65536 hard-coded), visto que o limite (na verdade, até mesmo a natureza de qualquer comportamento de um stack excessivamente grande) não é especificado. Algumas engines irão jogar uma excessão. De uma forma mais incisiva, outras engines irão limitar de forma arbitrária o número de argumentos que poderção ser aplicados à função. (Para ilustrar esse último caso: se uma engine dessas tem um limite de quatro argumentos [obviamente, os limites atuais são significativamente maiores], isso seria como se os argumentos5, 6, 2, 3 do exemplo anterior fossem passados aoapply, ao invés do array completo.) Se o valor do seu array puder crescer à casa das dezenas de centenas, use uma estratégia híbrida: aplique suas funções em cada bloco de array por vez:

function minOfArray(arr) {  var min = Infinity;  var QUANTUM = 32768;  for (var i = 0, len = arr.length; i < len; i += QUANTUM) {    var submin = Math.min.apply(null, arr.slice(i, Math.min(i + QUANTUM, len)));    min = Math.min(submin, min);  }  return min;}var min = minOfArray([5, 6, 2, 3, 7]);

Usando apply em "monkey-patching"

Apply pode ser a melhor forma de monkey-patch uma função nativa do Firefox, ou de bibliotecas em JS. Dada uma funçãosomeobject.foo, você poderá modificar a função de uma maneira hackeresca, como por exemplo:

var originalfoo = someobject.foo;someobject.foo = function () {  // Faça coisas antes de chamar a função  console.log(arguments);  // Chama a função como se ela estivesse sido chamada normalmente:  originalfoo.apply(this, arguments);  // Rode as coisas que vem depois, aqui.};

Esse método é especialmente útil quando você quer fazer debug de eventos, ou interagir com algo que não tem nenhuma API como os diversos eventos.on([event]... events, por exemplo aqueles utilizáveis noDevtools Inspector).

Especificações

Compatibilidade com navegadores

Veja também

• Objetoarguments
• Function.prototype.bind()
• Function.prototype.call()
• Funções e escopo de funções