Function.prototype.bind()

Experimente

const module = {
  x: 42,
  getX: function () {
    return this.x;
  },
};

const unboundGetX = module.getX;
console.log(unboundGetX()); // The function gets invoked at the global scope
// Expected output: undefined

const boundGetX = unboundGetX.bind(module);
console.log(boundGetX());
// Expected output: 42

Sintaxe

function.bind(thisArg[, arg1[, arg2[, ...]]])

Parmetros

thisArg

O valor a ser passado como parmetro this para a funo de destino quando a funo vinculada chamada. O valor ignorado se a funo ligada construda usando o operador new.

arg1, arg2, ...

Argumentos que precedem outros argumentos fornecidos para a funo vinculada ao invocar a funo de destino.

Valor de retorno

Uma cpia da funo fornecida com o valor this especificado e argumentos iniciais.

Descrio

A funo bind() cria uma nova funo vinculada (bound function). Uma funo vinculada um objeto de funo extico (termo da ECMAScript 2015) que encapsula o objeto de funo original. Chamar uma funo vinculada geralmente resulta na execuo de sua funo encapsulada.

Uma funo vinculada tem as seguintes propriedades internas:

• [[BoundTargetFunction]] - o objeto de funo encapsulado;
• [[BoundThis]] - o valor que sempre passado como this quando se chama a funo encapsulada;
• [[BoundArguments]] - uma lista de valores cujos elementos so usados como os primeiros argumentos para qualquer chamada da funo encapsulada;
• [[Call]] - executa cdigo associado com este objeto. Invocado atravs de uma expresso de chamada de funo. Os argumentos para o mtodo interno so um valor this e uma lista contendo os argumentos passados para a funo por uma expresso de chamada.

Quando a funo vinculada chamada, ela chama seu mtodo interno [[Call]] na [[BoundTargetFunction]], na forma Call(boundThis, args), onde boundThis [[BoundThis]] e args [[BoundArguments]] seguido pelos argumentos passados pela chamada de funo.

Uma funo vinculada tambm pode ser construda usando-se o operador new; ao faz-lo, o resultado o mesmo que seria se a funo alvo tivesse sido construda. O valor de this fornecido ignorado, porm os argumentos precedentes so fornecidos funo emulada.

Exemplos

Criando uma funo vinculada

O uso mais simples de bind() fazer com que uma funo que, independentemente da chamada, chamada com um determinado valor this. Um erro comum para programadores JavaScript novatos extrair um mtodo de um objeto e, em seguida, chamar essa funo e esperar que ele use o objeto original como o seu this (por exemplo, usando esse mtodo num cdigo baseado em callback). Sem a devida ateno, no entanto, o objeto original normalmente perdido. Criar uma funo vinculada a partir da funo, usando o objeto original, resolve perfeitamente esse problema:

this.x = 9; //this aqui se refere ao objeto global "window" do navegador
var module = {
  x: 81,
  getX: function () {
    return this.x;
  },
};

module.getX(); // 81

var retrieveX = module.getX;
retrieveX();
// retorna 9 - a funo foi invocada no escopo global

// Criando uma nova funo com 'this' vinculada ao mdulo
// Programadores novatos podem confundir a varivel x
// global com a propriedade x do mdulo
var boundGetX = retrieveX.bind(module);
boundGetX(); // 81

Funes parcialmente aplicadas

O prximo uso mais simples de bind() criar uma funo com argumentos iniciais pr-especificados. Esses argumentos (caso existam) acompanham o valor this fornecido e ento so inseridos no incio dos argumentos passados para a funo alvo, seguidos pelos argumentos passados para a funo vinculada, sempre que a funo vinculada chamada.

function list() {
  return Array.prototype.slice.call(arguments);
}

var list1 = list(1, 2, 3); // [1, 2, 3]

// Cria uma funo com um argumento principal predefinido
var leadingThirtysevenList = list.bind(null, 37);

var list2 = leadingThirtysevenList();
// [37]

var list3 = leadingThirtysevenList(1, 2, 3);
// [37, 1, 2, 3]

Com setTimeout

Por padro, dentro de window.setTimeout() a palavra-chave this vai ser definida com o objeto window (ou com o objeto global). Ao trabalhar com mtodos de classes que requerem que this se refira instncias de classes, voc pode vincular this explicitamente funo de callback, de modo a manter a instncia.

function LateBloomer() {
  this.petalCount = Math.ceil(Math.random() * 12) + 1;
}

// Declarar bloom depois de um intervalo de 1 segundo
LateBloomer.prototype.bloom = function () {
  window.setTimeout(this.declare.bind(this), 1000);
};

LateBloomer.prototype.declare = function () {
  console.log("I am a beautiful flower with " + this.petalCount + " petals!");
};

var flower = new LateBloomer();
flower.bloom();
// depois de 1 segundo, ativa o mtodo 'declare'

Funes vinculadas usadas como construtores

Funes vinculadas so automaticamente adequadas para uso com o operador new para construir novas instncias criadas pela funo alvo. Quando uma funo vinculada usada para construir um valor, o this fornecido ignorado. Porm, argumentos fornecidos ainda so prefixados chamada do construtor:

function Point(x, y) {
  this.x = x;
  this.y = y;
}

Point.prototype.toString = function () {
  return this.x + "," + this.y;
};

var p = new Point(1, 2);
p.toString(); // '1,2'

// no suportado no polyfill abaixo,
// funciona bem com o bind nativo:

var YAxisPoint = Point.bind(null, 0 /*x*/);

var emptyObj = {};
var YAxisPoint = Point.bind(emptyObj, 0 /*x*/);

var axisPoint = new YAxisPoint(5);
axisPoint.toString(); // '0,5'

axisPoint instanceof Point; // true
axisPoint instanceof YAxisPoint; // true
new Point(17, 42) instanceof YAxisPoint; // true

Note que voc no precisa fazer nada de especial para criar uma funo vinculada para usar com new. O corolrio que voc no precisa fazer nada de especial para criar uma funo vinculada que ser chamada de forma clara, mesmo que voc preferisse que a funo vinculada fosse somente chamada usando-se new.

// Exemplo pode ser executado diretamente no seu console JavaScript
// ...continuando o exemplo acima

// Ainda pode ser chamada como uma funo normal
// (apesar de que isso geralmente no  desejado)
YAxisPoint(13);

emptyObj.x + "," + emptyObj.y;
// >  '0,13'

Se voc quer suportar o uso de uma funo vinculada somente atravs de new, ou somente a chamando, a funo alvo deve impor essa restrio.

Criando atalhos

bind() itambm til em casos onde voc quer criar um atalho para uma funo que requer um valor especfico de this.

Tome por exemplo Array.prototype.slice, que voc quer usar para converter um objeto array-like em um vetor verdadeiro. Voc poderia criar um atalho assim:

var slice = Array.prototype.slice;

// ...

slice.apply(arguments);

Com bind(), isso pode ser simplificado. No seguinte trecho de cdigo, slice uma funo vinculada funo apply() de Function, com o valor this definido com a funo slice() de Array. Isso significa que chamadas adicionais de apply() podem ser eliminadas:

// mesmo que "slice" no exemplo anterior
var unboundSlice = Array.prototype.slice;
var slice = Function.prototype.apply.bind(unboundSlice);

// ...

slice(arguments);

Polyfill

A funo bind uma adio ECMA-262, 5. edio; como tal, pode no estar presente em todos os navegadores. Voc pode contornar isso parcialmente inserindo o seguinte cdigo no comeo de seus scripts, permitindo o uso de muita parte da funcionalidade de bind() em implementaes que no a suportam nativamente.

if (!Function.prototype.bind) {
  Function.prototype.bind = function (oThis) {
    if (typeof this !== "function") {
      // mais prximo possvel da funo interna
      // IsCallable da ECMAScript 5
      throw new TypeError(
        "Function.prototype.bind - what is trying to be bound is not callable",
      );
    }

    var aArgs = Array.prototype.slice.call(arguments, 1),
      fToBind = this,
      fNOP = function () {},
      fBound = function () {
        return fToBind.apply(
          this instanceof fNOP ? this : oThis,
          aArgs.concat(Array.prototype.slice.call(arguments)),
        );
      };

    fNOP.prototype = this.prototype;
    fBound.prototype = new fNOP();

    return fBound;
  };
}

Algumas das muitas diferenas ( bem possvel que haja outras, j que esta lista no pretende seriamente ser completa) entre este algoritmo e o algoritmo especificado so:

• Esta implementao parcial depende dos mtodos internos Array.prototype.slice(), Array.prototype.concat(), Function.prototype.call() e Function.prototype.apply() possurem seus valores originais.
• Esta implementao parcial cria funes que no tem um caller imutvel como "mecanismo de defesa" e propriedades arguments que lanam um TypeError ao usar get, set, ou ao deletar. (Isto pode ser adicionado se a implementao suporta Object.defineProperty, ou parcialmente implementado sem um comportamento throw-on-delete se a implementao suporta as extenses Object.prototype.__defineGetter__() e Object.prototype.__defineSetter__())
• Esta implementao parcial cria funes que tem uma propriedade prototype. (Funes vinculadas apropriadas no a tem.)
• Esta implementao parcial cria funes vinculadas cuja propriedade length no cumpre com a regra da ECMA-262: cria funes com comprimento zero, quando uma implementao completa, dependendo do comprimento da funo alvo e do nmero de argumentos pre-especificados, pode retornar um comprimento no-nulo.

Se voc escolher utilizar esta implementao parcial, voc no deve confiar em casos onde o comportamento diferente da ECMA-262, 5. edio! Porm, com algum cuidado (e talvez com modificao adicional para atender necessidades especficas), esta implementao parcial pode ser uma ponte razovel para quando bind() for amplamente implementada de acordo com a especificao.

Especificaes

Compatibilidade com navegadores

Veja tambm

• Function.prototype.apply()
• Function.prototype.call()
• Functions