.one()

类别：事件 > 事件处理函数附件

.one( events [, data ], handler )返回类型：jQuery

描述：把一个处理函数附加到针对元素的一个事件。 此处理函数针对每个元素每种事件类型最多执行一次。

  • 增补版本：1.1.one( events [, data ], handler )

    • events
      类型：String
      一个字符串，包含了一个或多个JavaScript事件类型，譬如“click”或“submit”或自定义事件名称。
    • data
      类型：PlainObject
      当触发事件时，在event.data中传递给处理函数的数据。
    • handler
      类型：Function( Event eventObject )
      事件被触发时要执行的函数。

  • 增补版本：1.7.one( events [, selector ] [, data ], handler )

    • events
      类型：String
      一个或多个空格隔开的事件类型名称，以及可选的命名空间，譬如“click”或“keydown.myPlugin”。
    • selector
      类型：String
      一个选择器字符串，筛选了触发此事件的选中的元素的后代。如果此选择器是null或省略了它，当事件到达选中的元素时，此事件始终触发。
    • data
      类型：Anything
      当触发事件时，在event.data中传递给处理函数的数据。
    • handler
      类型：Function( Event eventObject )
      当触发事件时要执行的函数。允许传入值false，作为仅仅函数function(){return false}的简写。

  • 增补版本：1.7.one( events [, selector ] [, data ] )

    • events
      类型：PlainObject
      一个对象，其中字符串键代表一个或多个空格隔开的事件类型，以及可选的命名空间，而值代表针对此事件要调用的处理函数。
    • selector
      类型：String
      一个选择器字符串，筛选了触发此事件的选中的元素的后代。如果此选择器是null或省略了它，当事件到达选中的元素时，始终调用此处理函数。
    • data
      类型：Anything
      当触发事件时，在event.data中传递给处理函数的数据。

.one()方法等同于.on()，除了针对一个给定元素、一个事件类型的此处理函数在第一次调用之后被解除绑定。例如：

1
2
3
 
$( "#foo" ).one( "click", function() {
  alert( "This will be displayed only once." );
});

执行此代码之后，点击带有ID=foo的元素将显示一个警告。后续的点击将不会有反应。此代码等同于：

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

换句话说，从正常绑定的处理函数内部显式调用.off()也具有相同的效果。

如果第一个参数包含了不止一个用空格隔开的事件类型，会针对每种事件类型调用一次事件处理函数。

1
2
3
 
$( "#foo" ).one( "click mouseover", function( event ) {
  alert( "The " + event.type + " event happened!" );
});

在上面的示例中，警告可以显示两次，因为绑定了两种事件类型（click和mouseover）。

示例：

给每个<div>绑一次点击：

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
38
39
40
41
42
43
44
45
46
47
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>one demo</title>
  <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-1.10.2.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>

演示：

若要在每个段落第一次被点击时，在一个警告框中显示所有段族的文本：

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

事件处理函数将对每个事件类型每个元素触发一次。

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.10.2.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>

演示：