页面控制--移动端开发手势库Hammer.JS使用文档

Hammer.js介绍:

• Hammer.js是一个轻量级的触屏设备的手势插件库,它能帮我们识别出在移动端开发过程中遇到的触摸,拖动,长按,滑动,手指平移,双指捏拿缩放等常见的用户手势操作.

• Hammer.js不需要依赖任何JS库,并且它的体积较小,生产环境的Hammer.js体积为7.34KB.

• Hammer.js官网地址http://hammerjs.github.io/getting-started/.

• Hammer.js 下载地址:

  1. 正式版: http://hammerjs.github.io/dist/hammer.min.js
  2. 开发版: http://hammerjs.github.io/dist/hammer.js
  3. Github源码地址: https://github.com/hammerjs/hammer.js/tree/master/

• Harmmer可以运行在除了IE8-的任何地方。浏览器若对触摸行为（touch-action）提供原生支持，那么对比那些不支持的浏览器，会有更好的体验。可通过查看touch-action页面了解更多。

注意:

• 本文档针对Hammer.js2.0.8版本,上文的下载链接均为2.0.8版本
• Hammer.js2.0.8已将整个插件完全重写,在这个版本中,它具有可重复使用的手势识别器，并在可能的情况下通过使用touch-action css属性改进了对最新移动浏览器的支持。同时支持多个Hammer实例，因此多点触摸成为可能。
• 若想了解之前的版本可以访问https://github.com/hammerjs/hammer.js/tree/1.1.x
• 本插件提供移动端手势监听功能,当是并没有封装手势对应的事件反馈,所以事件处理逻辑需要自己进行定义
• 本JS插件是本人目前所能寻找到比较全且比较新的移动端手势.
• 本文档为参照官方文档进行整理总结后进行编撰.

---

1. 插件引入方式

1. 直接在页面使用script标签引入

<scirpt src='http://hammerjs.github.io/dist/hammer.min.js'></script>

以上是从线上引入文件,各位大可将其下载到本地,然后进行引入

2. npm方式引入

npm install hammerjs

---

2.基本使用方法演示

1. css:

<style>

test{
				width: 200px;
				height: 200px;
				background-color: royalblue;
	}

</style>

---

2. html:

<div class = 'test'></div>

---

3. JavaScript:

1. 获取dom:

   var tst = document.querySelector(.test)

2. 创建Hammer实例对象:

   var hammers = new Hammer(tst)

   • Hammer是一个构造函数,它会返回一个带有一系列默认的手势识别器集合的实例对象Manager(管理者）

   • 在创建实例对象的时候，需要可以传递两个参数，参数一为页面上的一个dom元素，参数二为可选参数，它可以接收一个数组，这个数组可以写入需要使用到的手势识别器，若不给这个参数，则会默认开启tap, doubletap, pan, swipe, press, pinch, rotate这些默认的手势识别器，且不会有额外的识别器被开启.

3. 简单的几句代码，监听滑动、长按事件:

var hammers = new Hammer(document.getElementById('test'));
hammerTest.on('pan panmove swipe swipeup press pressup', function(ev) {
    console.log(ev.type);
});
//默认情况下，它增加了一组tap，doubletap，press，水平 pan和swipe和多点触控pinch和rotate识别。默认情况下，收缩识别器和旋转识别器是禁用的，因为它们会使元素阻塞，但是可以通过调用以下命令来启用它们
hammertime.get('pinch').set({ enable: true });
hammertime.get('rotate').set({ enable: true });

4. 点击查看基础实例

---

3.Hammer.js监听的事件类型

1. pan事件(拖拽):

在绑定的dom区域内，一个手指放下并移动事件，即触屏中的手指按住并移动事件,类似于拖拽操作,这个事件在屏触开发中比较常用

事件名	描述
pan	手指按住移动
Panstart	开始拖拽(手指按下并开始移动)
Panmove	拖拽中(手指按住并移动)
Panend	拖拽结束(手指松开,停止移动)
Pancancel	取消拖拽
Panleft	向左拖拽
Panright	向右拖拽
Panup	向上拖拽
Pandown	向下拖拽

• 注意:

  垂直方向上的拖拽事件一般是用来滚动页面的,所以hammer默认是不开启垂直方向的垂直方向的pan事件,

  若需要使用垂直方向的pan事件需要通过实例对象开启pan事件的垂直方向:

  hammers.get('pan').set({

  direction:Hammer.DIRECTION_ALL

  })

2. pinch事件(捏拿缩放):

在绑定的dom区域内，两个手指（默认为两个手指，多指触控需要单独设置）或多个手指相对（越来越近）移动或相向（越来越远）移动时事件

事件名	描述
Pinchstart	多点触控开始(两个手指按下)
Pinchmove	多点触控进行中(两个手指按下并开始移动)
Pinchend	多点触控结束(两个手指松开)
Pinchcancel	多点触控取消
Pinchin	多点触控两指距离越来越近(常用于缩小)
Pinchout	多点触控时两指距离越来越远(常用于放大)

注意:

• Pinchin,Pinchout同样有可能触发浏览器的页面放大和缩小的默认事件,所以在使用这两个方法的时候,最好将浏览器的缩放禁用掉

• pinch事件默认是不可用的,因为他们可能会导致元素被卡死,若想使用,要先使用以下方法开启这个事件:

  hammers.get('pinch').set({

  ​ enable = true

  })

  ---

3. press事件(长按)

在绑定的dom区域内触屏版本的点击事件，这个事件相当于PC端的Click事件，此事件不能包含任何的移动，最小按压时间为500毫秒，常用于我们在手机上用的“复制、粘贴”等功能。

事件名	描述
press	按住
pressup	松开

注意:

• 若绑定的dom区域内包含有文本元素,使用press事件会触发默认的文字选中功能,若不想发生这种的情况,为该dom元素指定CSS属性:user-selector:none

[注]每一个事件识别器可以看做为一个实例，我们可以将一个识别器赋值给一个变量如：

  mc.add( new Hammer.Tap({ event: 'tap4', taps: 4 }) );
  mc.on('tap4',(ev)=>{
      console.log(ev.type)
  })
	

---

4. rotate事件(旋转)

在绑定的dom区域内，当两个手指或更多手指成圆型旋转时触发（就像两个手指拧螺丝一样）。

事件名	描述
rotatestart	旋转开始(双指按住并开始旋转)
rotatemove	旋转过程
rotateend	旋转结束
rotatecancel	取消旋转

注意:

• rotate事件与pinch一样会造成dom元素的被卡死,所以默认也不开启这个事件,若想使用需要通过以下代码将rotate事件开启:

  hammers.get('rotate').set({

  ​ enable = true

  })

---

5. swipe事件(滑动)

在绑定的dom区域内，一个手指快速的在触屏上滑动。即我们平时用到最多的滑动事件。

事件名	描述
swipe	滑动
swipeleft	向左滑
swiperight	向右滑
swipeup	向上滑
swipedown	向下滑

注意:

• 一般情况下垂直方向的滑动是可以用于页面的滚动的,所以swipe默认是不开启Swipeup,Swipedown事件的,若需要使用,可以通过实例对象来设置Swipe事件的方向:

  hammers.get('swipe').set({

  direction:Hammer.DIRECTION_ALL

  })

  DIRCTION_ALL表示开启swipe的所有方向

  除了跟方位名词外,还可以使用数值

---

5. tap事件（点击）

在指定的dom区域内，一个手指轻拍或点击时触发该事件(类似PC端的click)。该事件最大点击时间为250毫秒，如果超过250毫秒则按Press事件进行处理。

事件名	类型
tap	点击
doubletap	双击

---

4. Hammer对象：

1.Hammer.defaults

• Hammer.defaults是在生成实例对象时的初始化默认值，包括定义的options识别器列表也就是在new Hammer是第二个参数写入的需要开启的手势识别器，Hammer.defaults也是一个对象

  

属性说明：

1. tocuhAction:

识别器选项,其值可为 compute, auto, pan-y, pan-x 或 none 。默认选项会基于识别器为你选择一个正确值。

2. domEvents: false:

是否禁用DOM事件，由hammer对象点出，取值为布尔值，如果你想实现事件委托，那么建议你将其设为true。

3. enable:true：

所有识别器都会有一个enable选项，其值为boolean或者一个回调函数，用来启用/禁用非底层的识别器。

4. cssProps:

可以改善交互事件操作的系列css属性。更多详情可以查阅JSDoc。

6. preset:

创建Hammer实例的时候就安装了默认的识别器。如果建立一个新的Manager（监听器容器），这些将会被覆盖。

---

2. Hammer.Manager:

Manager是所有识别器实例的容器，它为你的元素安装了交互事件监听器，并设置了触摸事件的一些特性。

可以使用Hammer.Manager的方式来生成实例对象，这样方法可以在生成实例对象的时候设置好监听器的一些特性，例如：

var hammer = new Hammer.Manager(myElement, {
    recognizers: [
        // RecognizerClass, [options], [recognizeWith, ...], [requireFailure, ...]
        [Hammer.Rotate],
        [Hammer.Pinch, { enable: false }, ['rotate']],
        [Hammer.Swipe,{ direction: Hammer.DIRECTION_HORIZONTAL }],
    ]
    //参数为你的元素（HTMLElement）和选项（options），传递的选项就是手势识别器的名称，随后合并到Hammer.defaults中的preset数组里面
});

通过设置recogizers属性中的值来设置识别器的特性，此属性是一个数组

3. Hammer对象实例方法:

1.hammers.get(string).set(options):

get方法可以理解为获取识别器，这个方法需要一个识别器作为参数，在获取后点出.set方法可在需要的时候修改识别器的特性，如控制是否启用此识别器，设置pen，swipe识别器的方向

(get方法由生成的实例对象点出)

语法：

mc.get('swipe').set({ enable: true });
//开启swipe快速滑动事件识别器

2.add(Recognizer) 和 remove(Recognizer)：

(Recognizer意为识别器)

添加一个新的Recognizer实例到Manager中，添加的顺序跟识别器执行的顺序一致。
get和remove方法都把一个（识别器中的）事件名或识别器实例来作为一个参数。
Add 和 remove 方法也接受一个识别器数组来作为参数

(add,remove方法由生成的实例对象点出)

hammers.add(myPinchRecognizer); 
//添加一个自定义手势识别器（在下文会对如何创建自定义手势识别器进行说明）
hammers.add([mySecondRecogizner, myThirdRecognizer]);
//添加多个自定义手势识别器，参数格式为数组
hammers.remove(myPinchRecognizer);
//移除一个自定义手势识别器
hammers.remove('rotate');
//移除rotate旋转手势
hammers.remove([myPinchRecognizer, 'rotate']);
//移除多个手势识别器，参数格式为数组

3.hammers.on(events, handler处理函数) 和 hammers.off(events, [handler])

hammers.on方法可以监听由被添加的识别器触发的事件：

hammers.on('tap swipe doubleTap',function（ev）{
          if(ev.type = 'tap'){
			console.log('tap')	    
		  }else if(ev.type = 'doubleTap'){
              console.log（'doubleTap'）
          }else{
              console.log('swipe')
          }
        })		
  //hammers.on可以同时监听多个识别器触发的事件，其方法就是各个识别器通过空格隔开作为参数传递进去
  //参数二是事件处理函数，通过判断ev.type可以判断当前触发事件的是哪一个识别器，从而执行不同的操作

hammers.off方法移除掉一些绑定的事件:

hammers.off('tap swipe doubleTap')

4.hammers.stop([force])

停止当前交互会话的识别器。当使用force参数时，将强制立刻停止识别器执行周期。

5.hammers.destroy()

解绑所有交互事件并让manager失去作用，但它没有解绑任何dom事件监听器。

---

4. Hammer.Recognizer

每一个识别器都是从这个Recognizer类中扩展出来的，所有识别器都会有一个enable选项，其值为boolean或者一个回调函数，用来启用/禁用非底层的识别器。

在控制台打印Hammer.Recognizer:

[注]使用生成的实例对象无法获取到Recognizer，只能通过Hammer对象点出

1.recognizeWith(otherRecognizer)

在当前识别器运行的时候需要同步运行或识别其它的识别器(otherRecognizer)时可以使用recognizeWith() 方法，比如当你需要在pan识别器被触发的同时监听到swipe手势识别器时，或者需要同时pinch缩放和ratate旋转一个dom元素。

recognizeWith())需要传递一个参数，这个参数是一个为字符串格式的识别器名，若有自定义的识别器，也可以作为参数传递进来，前提是这个自定义识别器必须是已经通过hammers.add方法添加到Manager识别器容器中,并且可以将一个存放识别器名称的数组作为参数传递进来，这个就可以在某个识别器被触发的过程中同时监听到其他多个识别器

具体使用方法：

	var hammers = new Hammer();
	hammers.get('swipe').set({
        enable:'true',
        direction:Hammer.DIRECTION_ALL 
    })
	hammers.get('pan').set({
        enable:'true',
        direction:Hammer.DIRECTION_ALL 
    })
	hammers.get('pinch').set({
        enable:'true' 
    })
	hammers.get('rotate').set({
        enable:'true' 
    })
	// swipe与pan的垂直方向以及pinch与rotate是默认禁止的，所以需要以上带先将其开启
	var pans = new Hammer.Pan();
	var swipes = new Hammer.Swipe();
	pans.recognizeWith(swipes)
	mc.on("pan swipe", function(ev) {
    myElement.textContent += ev.type +" ";
	});
	//现在，便可以在pan的同时监听到swipe。
	//若需要同时监听旋转和缩放
	var rotates = new Hammer.Rotate();
	var	pinch = new Hammer.Pinch();
	rotates.recognizeWith(swipes);
	//现在，便可以在rotate的同时监听到pinch。
	mc.on("pinch rotate", function(ev){
    myElement.textContent += ev.type +" ";
	});

官网推荐的recognizeWith()方法使用实例：同时识别（用RecognizeWith实现）Pinch和Rotate