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