# .bind()

所属分类：事件 > 绑定事件处理器 | 弃用 > 3.0 版本弃用的 API 英文文档：.bind()

## .bind( eventType [, eventData ], handler(eventObject) )返回: jQuery

描述: 为一个元素绑定一个事件处理程序。

- #### 添加的版本: 1.0.bind( eventType [, eventData ], handler(eventObject) )

  - eventType
    类型: String
    一个包含一个或多个DOM事件类型的字符串，比如"click"或"submit,"或自定义事件的名称。
  - eventData
    类型: Object
    一个对象，它包含的数据键值对映射将被传递给事件处理程序。
  - handler(eventObject)
    类型: Function()
    每当事件触发时执行的函数。

- #### 添加的版本: 1.4.3.bind( eventType [, eventData ], preventBubble )

  - eventType
    类型: String
    一个包含一个或多个DOM事件类型的字符串，比如"click"或"submit,"或自定义事件的名称。
  - eventData
    类型: Object
    一个对象，它包含的数据键值对映射将被传递给事件处理程序。
  - preventBubble
    类型: Boolean
    第三个参数设置为false将绑定一个函数，防止默认事件，阻止事件冒泡。默认值是true。

- #### 添加的版本: 1.4.bind( events )

  - events
    类型: Object
    一个对象，包含一个或多个DOM事件类型和函数并执行它们。

从jQuery 1.7开始，`.on()` 方法是将事件处理程序绑定到文档（document）的首选方法。对于早期版本，`.bind()`方法用于直接附加一个事件处理程序到元素上。处理程序附加到jQuery对象中当前选中的元素，所以，在`.bind()`绑定事件的时候，这些元素必须已经存在。对于更为灵活的事件绑定，可以查看`.on()` 或者 `.delegate()`事件代理。

对于`eventType`任何字符串是合法的;如果该字符串不是一个原生的DOM事件名称，那么以自定义事件方式绑定处理程序。这些事件是不会被浏览器调用，但可以通过其他JavaScript代码，例如使用`.trigger()`或`.triggerHandler()` 来手动触发。

如果`eventType`参数字符串包含一个点（ `.` ）字符，那么该事件是带命名空间的。这个点（ `.` ）字符将事件及其命名空间分隔开来。例如，在调用`.bind('click.name', handler)` ，字符串`click`是事件类型，而字符串`name`是命名空间。命名空间允许我们解除或绑定一些事件，而不会影响其他事件（注：即使是同类型的事件，命名空间不同，就不会受到影响。）。见`.unbind()`获取更多信息。

有一些标准的浏览器事件的简写方法，比如 `.click()`可以使用附加或触发事件处理程序。简写方法的完整列表，请参阅events category。

注：jQuery库提供了标准的事件类型绑定快捷方法,比如`.bind('click')`的快捷方法`.click()`。每一个描述中可以找到它的快捷方式：blur, focus, focusin, focusout, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, error。

当事件到达一个元素，该元素上绑定的所有与之相对应的类型的事件都会被触发。如果该元素上有多个处理程序注册，他们将永远在其中按固定的次序执行。所有处理程序执行完成后，事件继续沿着正常的事件传播路径继续传播事件。

`.bind()`一个基本的用法：

1 2 3 |
    $('#foo').bind('click', function() {  alert('User clicked on "foo."');});

此代码将使元素ID为`foo`响应`click`事件。当在用户点击这个元素之后，警报将显示。

#### Multiple Events（多个事件）

多个事件类型可以通过用空格隔开一次性绑定：

1 2 3 |
    $('#foo').bind('mouseenter mouseleave', function() {  $(this).toggleClass('entered');});

在`<div id="foo">`（当最初它不会有"entered"样式类时）上的这个效果是当鼠标进入`<div>`时增加"entered"样式类，鼠标离开时移除这个样式类。

在jQuery 1.4中，我们可以通过传递一个事件类型/处理函数的数据键值对映射来绑定多个事件处理程序，例如：

1 2 3 4 5 6 7 8 |
    $('#foo').bind({  click: function() {    // do something on click  },  mouseenter: function() {    // do something on mouseenter  }});

#### Event Handlers（事件处理程序）

`handler`参数需要一个回调函数，如上所述。在处理函数中， 关键字 `this` 指向当前所处理的 DOM 元素。为了该元素在jQuery中使用，它可以通过正常的`$()`函数。例如：

1 2 3 |
    $('#foo').bind('click', function() {  alert($(this).text());});

执行此代码后，当用户点击里面ID为`foo`的元素 ，它的文本内容将被显示为警告。

在jQuery 1.4.2中，重复的事件处理程序可以绑定到一个元素，而不是被丢弃。这对于使用 event data 功能时，或者是当其它唯一的数据保存在事件处理函数的闭包中时，特别有用。

在jQuery1.4.3，您现在可以通过传递`false`代替一个事件处理程序。这将相当于一个事件处理程序绑定写成这样：`function(){ return false; }`。在以后通过调用`.unbind( eventName, false )`来移除这个函数。

#### The Event object（事件对象）

在`handler`回调函数里还可以带参数。当函数被调用时，事件对象（event）将作为第一个参数被传递。

事件对象往往是不必要的，可以省略的参数，这是因为当触发事件处理时，我们可以通过上下文来取得足够的信息，完成我们需要的操作。然而，有的时候，当事件初始化完成时，我们需要收集更多关于用户环境的信息时，我们就需要使用该参数了。查看所有的事件对象。

从一个处理函数返回`false`等效于调用事件对象中的`.preventDefault()`和`.stopPropagation()`。

使用处理程序中的事件对象看起来像这样：

1 2 3 4 5 6 |
    $(document).ready(function() {  $('#foo').bind('click', function(event) {    alert('The mouse cursor is at ('      + event.pageX + ', ' + event.pageY + ')');  });});

请注意，参数添加到匿名函数。此代码将使 在点击ID为`foo`的元素的时候 alert光标在页面上的坐标位置。

#### Passing Event Data（传递事件数据）

可选的`eventData`参数不常用。当提供时，这种参数允许我们给处理函数传递额外的信息。一个方便的使用这个参数来解决由于闭包造成的问题。例如，假设我们有两个事件处理函数都引用了相同的外部变量：

1 2 3 4 5 6 7 8 |
    var message = 'Spoon!';$('#foo').bind('click', function() {  alert(message);});message = 'Not in the face!';$('#bar').bind('click', function() {  alert(message);});

由于两个事件处理函数的闭包中，都引用了 `message`，所以，当事件被触发时，这两个事件处理都会显示 Not in the face!，因为变量的值已经改变了。为了避免这个问题，我们可以使用 `eventData` 来传递信息：

1 2 3 4 5 6 7 8 |
    var message = 'Spoon!';$('#foo').bind('click', {msg: message}, function(event) {  alert(event.data.msg);});message = 'Not in the face!';$('#bar').bind('click', {msg: message}, function(event) {  alert(event.data.msg);});

这一次该变量没有提供给处理函数;相反，变量通过值传递给`eventData` ，所以就可以在事件绑定的时候进行赋值操作。 第一个处理程序，现在将显示Spoon!而第二个会提醒Not in the face!。

> 请注意，对象是通过参数传递给函数的，这种情况进一步复杂化。

如果`eventData`参数存在，那么第二个传递给`.bind()`的参数;如果没有更多的数据需要发送到处理程序，那么回调函数传递作为第二个也就是最后一个参数。

> 见`.trigger()`方法来了解如何在事件发生时向事件处理函数中传入参数，而不是在事件绑定的时候传递数据。

从 jQuery 1.4 开始，我们再也不能附加数据（和事件）到对象，embed，或applet元素了， 因为当附加数据到Java的applet时会发生严重错误。

注意: 虽然表现在下面的例子中， 绑定 `click` 和`dblClick`事件处理程序到相同的元素，这是不可取的。 各个浏览器事件触发的顺序是不同的， 一些浏览器在`dblclick`之前接受两个 `click` 事件 ，而和其它浏览器只接受一个 `click` 事件。 用户往往可通过不同的操作系统和浏览器配置双击灵敏度（ 点击之间的最大时间被检测为双击）。

## 例子:

#### Example: 为段落标签绑定单击和双击事件。请注意：坐标是相对于窗口的，所以在这个例子中是相对于 iframe 的。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
    <!DOCTYPE html><html><head>  <style>p { background:yellow; font-weight:bold; cursor:pointer;padding:5px; }p.over { background: #ccc; }span { color:red; }</style>  <script src="https://code.jquery.com/jquery-latest.js"></script></head><body>  <p>Click or double click here.</p><span></span><script>$("p").bind("click", function(event){var str = "( " + event.pageX + ", " + event.pageY + " )";$("span").text("Click happened! " + str);});$("p").bind("dblclick", function(){$("span").text("Double-click happened in " + this.nodeName);});$("p").bind("mouseenter mouseleave", function(event){$(this).toggleClass("over");}); </script> </body></html>

#### Demo:

#### Example: 点击段落时，显示其中的内容：

1 2 3 |
    $("p").bind("click", function(){alert( $(this).text() );});

#### Example: 在事件处理之前，你可以传入一些额外的数据：

1 2 3 4 |
    function handler(event) {alert(event.data.foo);}$("p").bind("click", {foo: "bar"}, handler)

#### Example: 通过返回 `false` 的方式取消默认的动作，并防止它进行事件冒泡：

1 |
    $("form").bind("submit", function() { return false; })

#### Example: 通过使用 .preventDefault() 方法，仅取消默认的动作。

1 2 3 |
    $("form").bind("submit", function(event) {event.preventDefault();});

#### Example: 通过使用 .stopPropagation() 方法，防止事件冒泡，但是默认执行默认的动作。

1 2 3 |
    $("form").bind("submit", function(event) {  event.stopPropagation();});

#### Example: 绑定自定义事件。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
    <!DOCTYPE html><html><head>  <style>p { color:red; }span { color:blue; }</style>  <script src="https://code.jquery.com/jquery-latest.js"></script></head><body>  <p>Has an attached custom event.</p><button>Trigger custom event</button><span style="display:none;"></span><script> $("p").bind("myCustomEvent", function(e, myName, myValue){$(this).text(myName + ", hi there!");$("span").stop().css("opacity", 1).text("myName = " + myName).fadeIn(30).fadeOut(1000);});$("button").click(function () {$("p").trigger("myCustomEvent", [ "John" ]);}); </script> </body></html>

#### Demo:

#### Example: 同时绑定多个事件。

1 2 3 4 5 6 7 8 9 10 11 |
    $("div.test").bind({  click: function(){    $(this).addClass("active");  },  mouseenter: function(){    $(this).addClass("inside");  },  mouseleave: function(){    $(this).removeClass("inside");  }});