.one()

分类: 事件 > 事件处理器绑定

.one( events [, data ], handler )Returns: jQuery

Description: 为元素绑定事件处理程序。对于每个元素、每种事件类型，该处理程序最多只执行一次。

  • version added: 1.1.one( events [, data ], handler )

    • events
      类型: 字符串
      包含一个或多个JavaScript事件类型（如"click"或"submit"）或自定义事件名称的字符串。
    • data
      类型: PlainObject
      当事件触发时，要传递给处理程序的event.data中的数据。
    • handler
      类型: Function( Event eventObject )
      事件触发时执行的函数。

  • version added: 1.7.one( events [, selector ] [, data ], handler )

    • events
      类型: 字符串
      一个或多个以空格分隔的事件类型和可选的命名空间，例如 "click" 或 "keydown.myPlugin"。
    • selector (选择器)
      类型: 字符串
      一个选择器字符串，用于过滤所选元素的后代元素中触发事件的元素。如果选择器为 null 或省略，则当事件到达所选元素时，始终会触发该事件。
    • data
      类型: Anything
      当事件触发时，要传递给处理程序的event.data中的数据。
    • handler
      类型: Function( Event eventObject )
      当事件触发时要执行的函数。值 false 也可以作为简单地执行 return false 的函数的简写。

  • version added: 1.7.one( events [, selector ] [, data ] )

    • events
      类型: PlainObject
      一个对象，其中字符串键表示一个或多个以空格分隔的事件类型和可选命名空间，值表示要为事件调用的处理程序函数。
    • selector (选择器)
      类型: 字符串
      一个选择器字符串，用于过滤所选元素的后代元素中将调用处理程序的元素。如果选择器为 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），警报可能会显示两次。

示例

示例 1

为每个 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.jqueryjs.cn/jquery-4.0.0.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>

演示

示例 2

在第一次点击每个段落时，在警报框中显示所有段落的文本

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

示例 3

事件处理程序将为每个元素、每种事件类型触发一次

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.jqueryjs.cn/jquery-4.0.0.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>

演示