jQuery.one() 函數用法實例詳解

one()函數用於為每個匹配元素的一個或多個事件綁定一次性事件處理函數。

此外，你還可以額外傳遞給事件處理函數一些所需的資料。

透過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程式碼：

<input id="btn" type="button" value="点击" />
<div id="n1">
    <p id="n2">段落文本内容1</p>
    <p id="n3">段落文本内容2</p>
    <span id="n4">隐藏关卡</span>
</div>
<div id="n5">
    <p id="n6">段落文本内容3</p>
    <p id="n7">段落文本内容4</p>
</div>
<p id="n8">专注于编程开发技术分享</p>

我們為上述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(&#39;<p id="n9">上述绑定的一次性click事件也会对该元素也生效!</p>&#39;);

請再參考以下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 );

以上是jQuery.one() 函數用法實例詳解的詳細內容。更多資訊請關注PHP中文網其他相關文章！