jquery one()方法绑定元素的一次性事件

使用one()方法绑定元素的一次性事件

one()方法可以绑定元素任何有效的事件，但这种方法绑定的事件只会触发一次，它的调用格式如下：

$(selector).one(event,[data],fun)

参数event为事件名称，data为触发事件时携带的数据，fun为触发该事件时执行的函数。

通过one()函数绑定的事件处理函数都是一次性的，只有首次触发事件时会执行该事件处理函数。触发之后，jQuery就会移除当前事件绑定。

此外，你可以为同一元素、同一事件类型绑定多个一次性的事件处理函数。触发事件时，

jQuery会按照绑定的先后顺序依次执行绑定的事件处理函数。

要删除通过one()绑定的事件，请使用unbind()或off()函数。

该函数属于jQuery对象(实例)。

语法

jQuery 1.1 新增该函数。one()函数主要有以下两种形式的用法：

用法一：

jQueryObject.one( events [, data ], handler )

为每个匹配元素的指定事件绑定事件处理函数。

用法二：jQuery 1.7 新增支持该用法。

jQueryObject.one( events , selector [, data ], handler )

在每个匹配元素上为所有符合指定选择器(selector)的后代元素的指定事件绑定事件处理函数。

用法三：jQuery 1.7 新增支持该用法。

jQueryObject.one( eventsMap [, selector ] [, data ] )

前面两种用法的变体。eventsMap是一个对象，其每个属性对应参数events，属性值对应参数handler。

参数

参数描述

events String类型一个或多个用空格分隔的事件类型和可选的命名空间，例

如"click"、"focus click"、"keydown.myPlugin"。

data 可选/任意类型触发事件时，需要通过event.data传递给事件处理函数的任意数据。

handler Function类型指定的事件处理函数。

selector String类型一个jQuery选择器，用于指定哪些后代元素可以触发绑定的事件。

eventsMap Object类型一个Object对象，其每个属性对应事件类型和可选的命名空间

(参数events)，属性值对应绑定的事件处理函数(参数handler)。

从jQuery 1.7开始，one()函数的用法和on()函数是完全一致的，只不过通过one()函数绑定的都是一次性的事件处理函数。

关于参数events中可选的命名空间(1.4.3+才支持)，请参考最下面的示例代码。

关于参数selector，你可以简单地理解为：如果该参数等于null或被省略，则为当前匹配元素绑定事件；否则就是为当前匹配元素的后代元素中符合selector选择器的元素绑定事件。

参数handler中的this指向当前匹配元素的后代元素中触发该事件的DOM元素。如果参数

selector等于null或被省略，则this指向当前匹配元素(也就是该元素)。

on()还会为handler传入一个参数：表示当前事件的Event对象。

参数handler的返回值与DOM原生事件的处理函数返回值作用一致。例如"submit"(表单提交)事件的事件处理函数返回false，可以阻止表单的提交。

如果事件处理函数handler仅仅只为返回false值，可以直接将handler设为false。

如果当前元素有多个匹配selector的后代元素，其中只要有任意一个后代元素触发执行了事

件处理函数，就会移除当前元素上的事件绑定，当前元素内符合条件的其他后代元素就无法再次触发执行。

返回值

one()函数的返回值为jQuery类型，返回当前jQuery对象本身。

示例&说明

我们为上述HTML中的按钮绑定一次性的click事件：

// 只有第一次点击时，执行该事件处理函数

// 执行后one()会立即移除绑定的事件处理函数

$("#btn").one("click", function(){

alert("只弹出一次提示框!");

});

此外，我们还可以同时绑定多个事件，并为事件处理函数传递一些附加的数据，我们可以通过jQuery为事件处理函数传入的参数event(Event事件对象)来进行处理：

$("#n4").one("mouseenter mouseleave", obj, function(event){

    var obj = event.data;

    var $me = $(this);

    if(event.type == "mouseenter"){

        $me.html( obj.name + '，你碰到了隐藏关卡，获得' + obj.hidden + "金币!"

);

    }else{

        $me.html( '你已通过该关卡!' );

    }



});

此外，如果符合条件的元素是在one()函数执行后新添加的，绑定事件依然会对其生效。同样以初始HTML代码为例，我们可以编写如下jQuery代码：

注意：虽然下面的jQuery代码是为n1元素的所有后代p元素绑定click事件，但事件处理函数本身是绑定在n1元素上的，后代p元素的click事件是委托给n1元素来处理的。只要n2、n3、n9中任意一个触发了click事件，就会移除body元素上绑定的事件处理函数。也就是说，n2、n3、n9总共只能执行一次该事件处理函数。

// 在n1元素上为所有后代p元素的click事件绑定事件处理函数

// 只有n2、n3可以触发该事件

$("#n1").one("click", "p", function(event){

alert( $(this).text() );

});

//新添加的n9也可以触发上述click事件，因为它也是n1的后代p元素

$("#n1").append('上述绑定的一次性click事件也会对该元素也生效!');

请再参考以下jQuery代码。div元素有两个，因此每个div元素都为后代p元素的click事件绑

定了事件处理函数。

// 在每个div元素上为其后代p元素的click事件绑定事件处理函数

// 只有n2、n3、n6、n7可以触发该事件

// n2和n3两者总共只能触发一次，n6和n7两者总共只能触发一次

$("div").one("click", "p", function(event){

alert( $(this).text() );

});

参数events还支持为事件类型附加额外的命名空间。当为同一元素绑定多个相同类型的事件处理函数时。使用命名空间，可以在触发事件、移除事件时限定触发或移除的范围。

function clickHandler(event){

alert( "触发时的命名空间:[" + event.namespace + "]");

}

var $p = $("p");

// A：为所有p元素绑定click事件，定义在foo和bar两个命名空间下

$p.one( "click.foo.bar", clickHandler );

// B：为所有p元素绑定click事件，定义在test命名空间下

$p.one( "click.test", clickHandler );

var $n2 = $("#n2");

/* 由于one()函数绑定的事件处理函数是一次性的，因此下面的每行代码只能分别执行，无法同时执行 */

// 触发所有click事件

$n2.trigger("click"); // 触发A和B (event.namespace = "")

// 触发定义在foo命名空间下的click事件

// $n2.trigger("click.foo"); // 触发A (event.namespace = "foo")

// 触发定义在bar命名空间下的click事件

// $n2.trigger("click.bar"); // 触发A (event.namespace = "bar")

// 触发同时定义在foo和bar两个命名空间下的click事件

// $n2.trigger("click.foo.bar"); // 触发A (event.namespace = "bar.foo")

// 触发定义在test命名空间下的click事件

// $n2.trigger("click.test"); // 触发B (event.namespace = "test")

one()函数的参数eventsMap是一个对象，可以"属性-值"的方式指定多个"事件类型-处理函数"。对应的示例代码如下：

var eventsMap = {

    "mouseenter": function(event){

        $(this).html( "Hello!");

    },



    "mouseleave": function(event){

        $(this).html( "Bye!");

    }

};

//为n5绑定mouseenter mouseleave两个事件

$("#n5").one( eventsMap );