hammer.js中文文檔

轉自：http://www.uedsc.com/hammerjs-api.html

HammerJS是一個優秀的、輕量級的觸屏設備手勢庫，如今已經更新到2.04版本，跟1.0版本有點天壤地別了，畢竟改寫了事件名並新增了許多方法，容許同時監聽多個手勢、自定義識別器，也能夠識別滑動方向。

不過對於新版本的hammerJS卻及其匱乏中文指引文檔，就着這一點我仍是上官網翻譯下英文文檔，寫一篇跟你們分享吧（其實hammer的API寫的很不怎樣，內容和排版都很馬虎了事，建議先仔細研究examples後再查閱。）。

注：本文將全部API中提到的 「input」 翻譯爲 「交互」，它實際包括mousedown, mousemove, touchmove, pointercancel事件。

 

GENERAL

開始

HammerJS是一個開源的庫，能夠識別由 touch, mouse 和 pointerEvents 觸發的系列手勢。它很是小巧，壓縮後僅有3.96kb，並無多餘的腳本依賴。

你能夠從Github上獲取最新版的HammerJS，或者直接下載壓縮版 或 未壓縮的開發版的HammerJS源碼。

點此獲取版本變更日誌。

也能夠點這裏獲取更舊的1.1版本。

2.0版本的變更：完全重寫了源碼，包括可複用的識別器（recognizer）、提高了對最新移動端瀏覽器可用的觸摸行爲css屬性的支持，另支持了多個hammer實例同時使用，讓多用戶同時使用一臺設備也不在話下。

使用

HammerJS的使用方式很是簡單，只要將庫引入到文件中，並建立一個新的實例便可：

var hammertime = new Hammer(myElement, myOptions);
hammertime.on('pan', function(ev) {
    console.log(ev);
});

它會默認爲這個對象添加一系列識別器，包括 tap<點>, doubletap<雙點擊>, press<按住>, 水平方位的pan<平移> 和 swipe<快速滑動>, 以及多觸點的 pinch<捏放> 和 rotate<旋轉>識別器。不過呢，其中的 pinch 和 rotate 默認是不可用的，由於它們可能會致使元素被卡住，若是你想啓用它們，能夠加上這兩句：

hammertime.get('pinch').set({ enable: true });
hammertime.get('rotate').set({ enable: true });

若要容許識別器識別垂直方位或所有方位的 pan 和 swipe，能夠這麼寫：

hammertime.get('pan').set({ direction: Hammer.DIRECTION_ALL });
hammertime.get('swipe').set({ direction: Hammer.DIRECTION_VERTICAL });

另建議加上以下meta標籤，防止doubletap 或 pinch 縮放了viewport：

<meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1, maximum-scale=1">

更多控制

你能夠爲你的實例設置屬於你本身的識別器，雖然要多寫一點代碼，但能讓你控制更多能被識別的手勢：

var mc = new Hammer.Manager(myElement, myOptions);

mc.add( new Hammer.Pan({ direction: Hammer.DIRECTION_ALL, threshold: 0 }) );
mc.add( new Hammer.Tap({ event: 'quadrupletap', taps: 4 }) );

mc.on("pan", handlePan);
mc.on("quadrupletap", handleTaps);

上述的代碼建立了一個實例（mc），它包含了一個 pan 和一個 quadrupletap 手勢，識別器實例會在它們被添加（add）以後就不斷地執行，且（一個識別器實例）只能識別一個（手勢）。

貼士和竅門

1. 試着避免垂直方向上的 pan/swipe

垂直方向上的平移操做通常是用來滾動你的頁面的，並且有些（過期的）瀏覽器不會傳遞事件，致使Hammer沒法識別這些手勢。你能夠嘗試換另外一種可替換的途徑來實現相同的動做。

2. 在設備上作測試

有時候Hammer須要作一些調整，像swipe的速率或其它閾值，若是你在一臺反應較慢的設備上作測試，那麼你要保證你的回調越簡單越好。有些站點例如JankFree.org上有專門的文章來介紹如何提高展現效果。

3. 去掉Windows Phone點擊時的高亮效果

你在Windows Phone上的IE10和IE11裏tap某元素時，會有一個小小的tap高亮效果，加上這個meta標籤能夠取消這種效果：

<meta name="msapplication-tap-highlight" content="no" />

4. 「我怎麼選擇不了文本了！」

Hammer設置了一個屬性用來提高桌面平移操做的用戶體驗（UX）。常規來講，當你在桌面級瀏覽器上拖動頁面時，你應該是能夠正常選中文本的，但user-select這個CSS屬性禁用了這功能。
若是你在乎文本選擇功能，同時以爲桌面級的體驗不必太盡善盡美，你能夠很輕鬆地取消這個默認選項——確保在建立實例以前執行：

delete Hammer.defaults.cssProps.userSelect;

5. 「在tap以後，致使觸發了一個click事件，我不想這樣！」
這種click事件咱們稱之爲一個「幽靈點擊」事件，我建立了一個小函數來避免觸摸後致使click，對此，Ryan Fioravanti的文章給了我很大的靈感。

瀏覽器/終端的支持

無須擔憂你的瀏覽器或系統不在下方的列表上，Harmmer能夠運行在除了IE8-的任何地方。瀏覽器若對觸摸行爲（touch-action）提供原生支持，那麼對比那些不支持的瀏覽器，會有更好的體驗。查看touch-action頁面瞭解更多。

實例

1. 基礎實例

2. 垂直方向的pan識別器

3. 同時識別（用RecognizeWith實現）Pinch和Rotate

4. 用RecognizeWith操做Quadrupletap（自定義的，表示4個tap）識別器

5. SingleTap<單點>和DoubleTap<雙點擊>(配合recognizeWith/requireFailure)

更多實例能夠查看github上的庫文件。

HAMMER

常規API

Hammer

Hammer.defaults

Hammer.Manager

Hammer.Recognizer

Hammer.input event

Event object

Constants

Utils

==============================

Hammer

建立並返回一個帶有系列默認識別器集合的Manager實例，該集合內包含了諸如 tap, doubletap, pan, swipe, press, pinch 和 rotate 識別器。你應該在初始化時執行它，其語法爲：

Contructor(HTMLElement, [options])

參數裏一個是你的頁面元素，另外一個是可選的識別器選項options，options會融入Hammer.defaults中去，固然，在Hammer.defaults.preset中定義的識別器集合也會被添加進來。

若是識別器選項options爲空，那麼初始化的時候不會有額外的識別器被添加進來：

var myElement = document.getElementById('hitarea');
var mc = new Hammer(myElement);

==============================

Hammer.defaults

建立實例時初始化的默認值，包括你定義的options選擇器項。其屬性包括：

touchAction: ‘compute’

其值可爲 compute, auto, pan-y, pan-x 或 none 。默認選項會基於識別器爲你選擇一個正確值。

domEvents: false
讓Hammer也能禁用DOM事件。若不由用會有些慢，故默認是禁用的。若是你想實現事件委託，那麼建議你將其設爲true。

enable: true
接受一個boolean值, 或返回一個boolean值的函數。（官網就這樣一句話，也沒說具體啥做用，汗~）

cssProps: {….}
能夠改善交互事件操做的系列css屬性。更多詳情能夠查閱JSDoc。

preset: [….]
調用Hammer()的時候就安裝了默認的識別器。若是創建一個新的Manager，這些將被跳過。

==============================

Hammer.Manager

Manager是全部識別器實例的容器，它爲你的元素安裝了交互事件監聽器，並設置了觸摸事件特性。

constructor(HTMLElement, [options])

參數爲你的元素（HTMLElement）和選項（options），選項將合併到Hammer.defaults中去：

var mc = new Hammer.Manager(myElement);

你能夠在選項中使用 recognizers 來設置一個初始化識別器，它是一個數組，寫法以下：

var mc = new Hammer.Manager(myElement, {
    recognizers: [
        // RecognizerClass, [options], [recognizeWith, ...], [requireFailure, ...]
        [Hammer.Rotate],
        [Hammer.Pinch, { enable: false }, ['rotate']],
        [Hammer.Swipe,{ direction: Hammer.DIRECTION_HORIZONTAL }],
    ]
});

set(options)

修改一個Manager實例的選項，該方法是推薦使用的，它能夠在須要的時候更新touchAction的值：

mc.set({ enable: true });

get(string), add(Recognizer) 和 remove(Recognizer)

添加一個新的Recognizer實例到Manager中，添加的順序跟識別器執行的順序一致。get方法會返回被添加的Recognizer實例。
get和remove方法都把一個（識別器中的）事件名或識別器實例來做爲一個參數。
Add 和 remove 方法也接受一個識別器數組來做爲參數：

// both return instance of myPinchRecognizer
mc.get('pinch');
mc.get(myPinchRecognizer);

mc.add(myPinchRecognizer); // returns the recognizer
mc.add([mySecondRecogizner, myThirdRecognizer]);

mc.remove(myPinchRecognizer);
mc.remove('rotate');
mc.remove([myPinchRecognizer, 'rotate']);

on(events, handler) 和 .off(events, [handler])

監聽由被添加的識別器觸發的事件，或者移除那些綁定了的事件。參數中將事件經過空格隔開可處理多個事件：

mc.on("pinch", function(ev) {
    console.log(ev.scale);
});

stop([force])

中止當前交互會話的識別器（Stop recognizing for the current input session）。當使用force參數時，將強制馬上中止識別器執行週期。

destroy()

解綁全部交互事件並讓manager失去做用，但它沒有解綁任何dom事件監聽器。

==============================

Hammer.Recognizer

每個識別器都是從這個類中擴展出來的，全部識別器都會有一個enable選項，其值爲boolean或者一個回調函數，用來啓用/禁用非底層的識別器。

constructor([options])

只有選項做爲參數：

var pinch = new Hammer.Pinch(); //建立一個識別器
mc.add(pinch); // 添加到Manager實例中

set(options)

在識別器實例中修改一個選項。該方法是推薦使用的，它能夠在須要的時候更新touchAction的值。

recognizeWith(otherRecognizer) 和 dropRecognizeWith(otherRecognizer)

在當前識別器運行的時候同步運行所給的其它識別器（otherRecognizer），當你須要在最後結合pan和swipe手勢時，或者須要同時pinch和ratate一個對象時，它會頗有幫助。
移除這種聯繫時，只會移除當前識別器上的鏈接，而不是其它識別器（otherRecognizer）上的鏈接。
這兩個方法都支持一個識別器組成的數組來做爲參數。
若是識別器被添加到了Manager上，那麼該方法也支持將其它識別器(otherRecognizer)的事件名（字符串形式）來做爲參數。

瞭解更多recognizeWith

requireFailure(otherRecognizer) 和 dropRequireFailure(otherRecognizer)

只有當其它識別器（otherRecognizer）無效時才執行該識別器。
移除這種聯繫時，只會移除當前識別器上的鏈接，而不是其它識別器（otherRecognizer）上的鏈接。
這兩個方法都支持一個識別器組成的數組來做爲參數。
若是識別器被添加到了Manager上，那麼該方法也支持將其它識別器(otherRecognizer)的事件名（字符串形式）來做爲參數。

瞭解更多requireFailure

==============================

Hammer.input 事件

hammer.input能夠觸發一個「祕密的」事件，它發生在每個接收中的交互中，也讓你能對原生的交互來作相關處理。它是一個小而強大的特性。

hammertime.on("hammer.input", function(ev) {
   console.log(ev.pointers);
});

==============================

事件對象

每個Hammer觸發的事件都會收到一個包含了以下屬性的事件對象：

==============================

常量/Constants（這個建議查閱源碼338行起，主要是用於標誌事件輪廓，可經過上文「事件對象」的direction、offsetDirection等屬性來獲取）

全部常量都定義於Hammer對象中，由於它們都是二進制標識，你可使用位運算來操做它們。MDN上有一些關於位運算的優秀文檔。

方位/Directions

用於定義一個識別器的方位，並用來讀取一個事件的對應值。

交互事件/Input Events

Hammer匹配全部交互 (mousedown, mousemove, touchmove, pointercancel)事件類型爲以下值：

識別器狀態/Recognizer States

由識別器在內部定義本身的狀態：

==============================

工具/Utils

Hammer.on(element, types, handler)

addEventListener的封裝，能夠接受多個事件類型爲參數：

Hammer.on(window, "load resize scroll", function(ev) {
    console.log(ev.type);
});

Hammer.off(element, types, handler)

如同Hammer.on，是removeEventListener的封裝，也容許多個事件類型爲參數。

Hammer.each(obj, handler)

遍歷一個數組或對象：

Hammer.each([10,20,30,40], function(item, index, src) { });
Hammer.each({a:10, b:20, c:30}, function(item, key, src) { });

Hammer.merge(obj1, obj2)

把obj2的屬性混到obj1中去，不過obj1的已有屬性不會被重寫：

var options = {
    b: false
};

var defaults = {
    a: true,
    b: true,
    c: [1,2,3]
};
Hammer.merge(options, defaults);

// options.a == true
// options.b == false
// options.c == [1,2,3]

Hammer.extend(obj1, obj2)

把obj2的屬性擴展到obj1中去，不過obj1的已有屬性會被重寫：

var obj1 = {
    a: true,
    b: false,
    c: [1,2,3]
};

var obj2 = {
    b: true,
    c: [4,5,6]
};
Hammer.extend(obj1, obj2);

// obj1.a == true
// obj1.b == true
// obj1.c == [4,5,6]

Hammer.inherit(child, base, [properties])

簡單的類繼承：

function Animal(name) {
    this.name = name;
}

function Dog() {
    Animal.apply(this, arguments);
}

Hammer.inherit(Dog, Animal, {
    bark: function() {
        alert(this.name);
    }
});

var dog = new Dog('Spaikie');
dog.bark();

Hammer.bindFn(fn, scope)

Function.bind的簡化形式：

function myFunction(ev) {
    console.log(this === myContext); // is true
}

var myContext = {
    a: true,
    b: false
};

window.addEventListener('load', Hammer.bindFn(myFunction, myContext), false);

Hammer.prefixed(obj, name)

獲取瀏覽器的（前綴）屬性值：

Hammer.prefixed(document.body.style, 'userSelect');
// returns "webkitUserSelect" on Chrome 35

關於hammer的API就翻譯到這裏，剩餘的幾個頁面內容篇幅較少也較好讀懂，請自行查閱和理解。