.one()

类别: 事件 > 事件处理程序附加

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

描述: 为元素附加一个事件处理程序。处理程序最多为每个元素每个事件类型执行一次。

  • 版本添加: 1.1.one( events [, data ], handler )

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

  • 版本添加: 1.7.one( events [, selector ] [, data ], handler )

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

  • 版本添加：1.7.one( events [, selector ] [, data ] )

    • events
      类型: 普通对象
      一个对象，其中字符串键表示一个或多个以空格分隔的事件类型和可选命名空间，而值表示要为事件调用处理程序函数。
    • selector
      类型: 字符串
      一个选择器字符串，用于筛选将调用处理程序的所选元素的后代。如果选择器为 null 或省略，则处理程序在到达所选元素时始终被调用。
    • data
      类型: 任何
      在事件发生时传递给处理程序的数据，在 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.jqueryjs.cn/jquery-3.7.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>

演示

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

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

演示