# .one()

所属分类：事件 > 绑定事件处理器 英文文档：.one()

## .one( events [, data ], handler(eventObject) )返回: jQuery

描述: 为元素的事件添加处理函数。处理函数在每个元素上每种事件类型最多执行一次。

- #### 添加的版本: 1.1.one( events [, data ], handler(eventObject) )

  - events
    类型: String
    一个包含一个或多个JavaScript事件类型的字符串，比如“click”或“submit”，或自定义的事件名称。
  - data
    类型: PlainObject
    一个对象，它包含的数据键值对映射将被传递给事件处理程序。
  - handler(eventObject)
    类型: Function()
    每次事件触发时会执行的函数。

- #### 添加的版本: 1.7.one( events [, selector ] [, data ], handler(eventObject) )

  - events
    类型: String
    一个或多个空格分隔的事件类型和可选的命名空间，或仅仅是命名空间，比如"click", "keydown.css88", 或者 ".myPlugin"。
  - selector
    类型: String
    ，一个选择器字符串，用于过滤出被选中的元素中能触发事件的后代元素。如果选择器是`null`或被省略，那么被选中的元素总是能触发事件。
  - data
    类型: Anything
    当一个事件被触发时，要传递给事件处理函数的`event.data`。
  - handler(eventObject)
    类型: Function()
    事件被触发时，执行的函数。若该函数只是要执行`return false`的话，那么该参数位置可以直接简写成 `false`。

- #### 添加的版本: 1.7.one( events [, selector ] [, data ] )

  - events
    类型: PlainObject
    一个映射，键是由一个或多个由空格分隔的事件类型及可选的名字空间，值是这些事件类型所对应的事件处理函数。
  - selector
    类型: String
    ，一个选择器字符串，用于过滤出被选中的元素中能触发事件的后代元素。如果选择器是`null`或被省略，那么被选中的元素总是能触发事件。
  - data
    类型: Anything
    当一个事件被触发时，要传递给事件处理函数的`event.data`。

这个方法的第一种形式（注：.one( events [, data ], handler(eventObject) 这种形式)）用法和`.bind()`相同，但`.one()`的处理函数第一次调用后绑定的事件就被解除了。第二两种形式（注：.one( events [, selector ] [, data ], handler(eventObject) )这种形式）， 在jQuery1.7中，它和`.on()`是相同的， 不同之处在于，不管选择器是否匹配到任何元素，或没有匹配任何元素，处理程序在委派的元素上触发事件后第一时间被删除，举个例子：

1 2 3 4 5 6 |
    $("#foo").one("click", function() {  alert("This will be displayed only once.");});$("body").one("click", "#foo", function() {  alert("This displays if #foo is the first thing clicked in the body.");});

在代码执行后，点击id为`foo`的元素将显示警报。之后再在该元素上点击时，就不会再触发该事件。此代码是等效于：

1 2 3 4 |
    $( "#foo" ).on( "click", function( event ) {  alert( "This will be displayed only once." );  $( this ).off( event );});

换句话说，在一个普通的事件绑定处理函数中，显式的调用 `.off()`和该方法的作用是一样的。

如果该方法的第一个参数包含多个用空格分隔的事件类型的话，那么每种类型的事件被触发时，处理函数仅会被每个事件类型调用一次。

## 例子:

#### Example: 为每个 div 绑定一次性 click 事件。

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 31 32 33 34 35 36 37 |
    <!DOCTYPE html><html><head>  <style>div { width:60px; height:60px; margin:5px; float:left;background:green; border:10px outset;cursor:pointer; }p { color:red; margin:0; clear:left; }</style>  <script src="https://code.jquery.com/jquery-latest.js"></script></head><body> <div></div><div></div><div></div><div></div><div></div> <p>Click a green square...</p> <script>var n = 0;$("div").one("click", function() {  var index = $("div").index(this);  $(this).css({    borderStyle:"inset",    cursor:"auto"  });  $("p").text("Div at index #" + index + " clicked." +      "  That's " + ++n + " total clicks.");}); </script> </body></html>

#### Demo:

#### Example: 在每个段落上第一次点击时，显示该段落的内容：

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

#### Example: 处理函数在每个元素上每种事件类型只执行一次。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
    <!doctype html><html lang="en"><head>  <meta charset="utf-8">  <title>one demo</title>  <script src="https://code.jquery.com/jquery-1.9.1.js"></script></head><body> <div class="count">0</div><div class="target">Hover/click me</div> <script>var n = 0;$(".target").one("click mouseenter", function() {  $(".count").html(++n);});</script> </body></html>

#### Demo: