事件處理 · Zepto.js API 中文文檔 1.1.6

# 事件處理 ## $.Event ``` $.Event(type, [properties]) => event ``` 創建并初始化一個指定的DOM事件。如果給定properties對象，使用它來擴展出新的事件對象。默認情況下，事件被設置為冒泡方式；這個可以通過設置`bubbles`為`false`來關閉。一個事件初始化的函數可以使用 [trigger](#trigger)來觸發。 ``` $.Event('mylib:change', { bubbles: false }) ``` ## $.proxy v1.0+ ``` $.proxy(fn, context) => function $.proxy(fn, context, [additionalArguments...]) => function v1.1.4+ $.proxy(context, property) => function $.proxy(context, property, [additionalArguments...]) => function v1.1.4+ ``` 接受一個函數，然后返回一個新函數，并且這個新函數始終保持了特定的上下文(context)語境，新函數中`this`指向context參數。另外一種形式，原始的function是從上下文(context)對象的特定屬性讀取。如果傳遞超過2個的額外參數，它們被用于傳遞給fn參數的函數引用。 ``` var obj = {name: 'Zepto'}, handler = function(){ console.log("hello from + ", this.name) } // ensures that the handler will be executed in the context of `obj`: $(document).on('click', $.proxy(handler, obj)) ``` ## bind 不推薦, 使用 [on](#on) 代替。 ``` bind(type, function(e){ ... }) => self bind(type, [data], function(e){ ... }) => self v1.1+ bind({ type: handler, type2: handler2, ... }) => self bind({ type: handler, type2: handler2, ... }, [data]) => self v1.1+ ``` 為一個元素綁定一個處理事件。 ## delegate 不推薦, 使用 [on](#on) 代替。 ``` delegate(selector, type, function(e){ ... }) => self delegate(selector, { type: handler, type2: handler2, ... }) => self ``` 基于一組特定的根元素為所有選擇器匹配的元素附加一個處理事件，匹配的元素可能現在或將來才創建。 ## die 不推薦, 使用 [on](#on) 代替。 ``` die(type, function(e){ ... }) => self die({ type: handler, type2: handler2, ... }) => self ``` 刪除通過 [live](#live) 添加的事件。 ## event.isDefaultPrevented v1.1+ ``` event.isDefaultPrevented() => boolean ``` 如果`preventDefault()`被該事件的實例調用，那么返回true。這可作為跨平臺的替代原生的 `defaultPrevented`屬性，如果 `defaultPrevented`缺失或在某些瀏覽器下不可靠的時候。 ``` // trigger a custom event and check whether it was cancelled var event = $.Event('custom') element.trigger(event) event.isDefaultPrevented() ``` ## event.isImmediatePropagationStopped v1.1+ ``` event.isImmediatePropagationStopped() => boolean ``` 如果`stopImmediatePropagation()`被該事件的實例調用，那么返回true。Zepto在不支持該原生方法的瀏覽器中實現它，（例如老版本的Android）。 ## event.isPropagationStopped v1.1+ ``` event.isPropagationStopped() => boolean ``` 如果`stopPropagation()`被該事件的實例調用，那么返回true。 ## live 不推薦, 使用 [on](#on) 代替。 ``` live(type, function(e){ ... }) => self live({ type: handler, type2: handler2, ... }) => self ``` 類似[delegate](#delegate)，添加一個個事件處理器到符合目前選擇器的所有元素匹配，匹配的元素可能現在或將來才創建。 ## off ``` off(type, [selector], function(e){ ... }) => self off({ type: handler, type2: handler2, ... }, [selector]) => self off(type, [selector]) => self off() => self ``` 移除通過 [on](#on) 添加的事件.移除一個特定的事件處理程序，必須通過用`on()`添加的那個相同的函數。否則，只通過事件類型調用此方法將移除該類型的所有處理程序。如果沒有參數，將移出當前元素上_全部_的注冊事件。 ## on ``` on(type, [selector], function(e){ ... }) => self on(type, [selector], [data], function(e){ ... }) => self v1.1+ on({ type: handler, type2: handler2, ... }, [selector]) => self on({ type: handler, type2: handler2, ... }, [selector], [data]) => self v1.1+ ``` 添加事件處理程序到對象集合中得元素上。多個事件可以通過空格的字符串方式添加，或者以事件類型為鍵、以函數為值的對象方式。如果給定css選擇器，當事件在匹配該選擇器的元素上發起時，事件才會被觸發（愚人碼頭注：即事件委派，或者說事件代理）。如果給定`data`參數，這個值將在事件處理程序執行期間被作為有用的 `event.data` 屬性事件處理程序在添加該處理程序的元素、或在給定選擇器情況下匹配該選擇器的元素的上下文中執行(愚人碼頭注：this指向觸發事件的元素)。當一個事件處理程序返回`false`，`preventDefault()` 和 `stopPropagation()`被當前事件調用的情況下，將防止默認瀏覽器操作，如鏈接。如果`false` 在回調函數的位置上作為參數傳遞給這個方法，它相當于傳遞一個函數，這個函數直接返回`false`。（愚人碼頭注：即將 `false` 當作 `function(e){ ... }` 的參數，作為 `function(){ return false; }` 的簡寫形式，例如： `$("a.disabled").on("click", false);`這相當于`$("a.disabled").on("click", function(){ return false; } );`） ``` var elem = $('#content') // observe all clicks inside #content: elem.on('click', function(e){ ... }) // observe clicks inside navigation links in #content elem.on('click', 'nav a', function(e){ ... }) // all clicks inside links in the document $(document).on('click', 'a', function(e){ ... }) // disable following any navigation link on the page $(document).on('click', 'nav a', false) ``` ## one ``` one(type, [selector], function(e){ ... }) => self one(type, [selector], [data], function(e){ ... }) => self v1.1+ one({ type: handler, type2: handler2, ... }, [selector]) => self one({ type: handler, type2: handler2, ... }, [selector], [data]) => self v1.1+ ``` 添加一個處理事件到元素，當第一次執行事件以后，該事件將自動解除綁定，保證處理函數在每個元素上最多執行一次。`selector` 和 `data` 等參數說明請查看[`.on()`](#on)。 ## trigger ``` trigger(event, [args]) => self ``` 在對象集合的元素上觸發指定的事件。事件可以是一個字符串類型，也可以是一個通過[$.Event](#$.Event) 定義的事件對象。如果給定args參數，它會作為參數傳遞給事件函數。 ``` // add a handler for a custom event $(document).on('mylib:change', function(e, from, to){ console.log('change on %o with data %s, %s', e.target, from, to) }) // trigger the custom event $(document.body).trigger('mylib:change', ['one', 'two']) ``` Zepto僅僅支持在dom元素上觸發事件。 ## triggerHandler ``` triggerHandler(event, [args]) => self ``` 像 [trigger](#trigger)，它只在當前元素上觸發事件，但不冒泡。 ``` $("input").triggerHandler('focus'); // 此時input上的focus事件觸發，但是input不會獲取焦點 $("input").trigger('focus'); // 此時input上的focus事件觸發，input獲取焦點 ``` ## unbind Deprecated, use [off](#off) instead. ``` unbind(type, function(e){ ... }) => self unbind({ type: handler, type2: handler2, ... }) => self ``` 移除通過 [bind](#bind) 注冊的事件。 ## undelegate Deprecated, use [off](#off) instead. ``` undelegate(selector, type, function(e){ ... }) => self undelegate(selector, { type: handler, type2: handler2, ... }) => self ``` 移除通過[delegate](#delegate) 注冊的事件。