【js】nipplejs摇杆库API总结

nipplejs摇杆库API总结by RAY 2017.03.13
前端web client页面虚拟摇杆库API翻译、使用总结

参考
官方http://yoannmoinet.github.io/nipplejs/

更新

【0】 概述

(日期17.03)当前版本支持以下功能：
1.固定&非固定位置摇杆，摇杆大小颜色位置可调。
2.返回读数有：摇杆位置xy，角度，半径等。小圆超过可见大圆外时，也是操控区域，读数也会增加。
3.支持监听事件（start,end,move,dir:up\down\right\left,pressure,
plain:up\down\right\left）。

在线下载最新版
npm install nipplejs –save
// OR
bower install nipplejs –save

【1】创建摇杆

body放置标签，通过nipplejs.create(option)创建摇杆对象

<div id="left"></div>
...
var joystick_1 = nipplejs.create({
    zone: document.getElementById('left'),
    mode: 'static',//mode: 'semi','dynamic'
    position: { left: '20%', top: '50%' },
    color: 'green',
    size: 200
});

参数Option的解析

var options = {
    zone: Element,                  //触控有效区域，用一个div标识
    color: String,        //’green’
    size: Integer,        //in px
    threshold: Float(1~0.9),       // 触发前后左右事件的灵敏度（当force>threshold才会触发事件）
    fadeTime: Integer,              // 粘滞时间（放手后摇杆缓慢复位的时间）
    multitouch: Boolean,
    maxNumberOfNipples: Number,     // when multitouch, what is too many?
    dataOnly: Boolean,              // no dom element whatever
    position: Object,               // preset position for 'static' mode
    mode: String,                   // 'dynamic非固定+不动隐藏', 'static固定' or 'semi非固定+不动变透明'
    restOpacity: Number,            // opacity when not 'dynamic' and rested
    catchDistance: Number           // distance to recycle previous joystick in
                                    // 'semi' mode
};

*threshold: 0~0.9 设置半径移动多大才算有效的动作，触发方向改变事件如dir:up等等。

还不懂请看实现代码：if (force > threshold) { 改变direction并触发方向改变事件 }

这里提供一个我自己用到的小技巧：摇杆大小自动适配屏幕大小

//取元素的百分百大小,返回px
function getSize(elem, percent) {
    var tem = (elem.clientWidth > elem.clientHeight ? elem.clientHeight : elem.clientWidth);
    return parseInt(tem * percent);
}
...
Var joystickL = nipplejs.create({
    zone: document.getElementById('left'),
    mode: 'dynamic',
    position: {left: '20%', top: '50%'},
    color: 'green',
    threshold: 0.4,
    size: getSize(document.body, 0.25)
});

【2】返回读数

摇杆Move时会通过回调函数实时返回数据
// 通过绑定事件获取数据

joystick.on('start end', function (evt, data) {
    debug(data);
}).on('move', function (evt, data) {
    debug(data);})
data对象：
{
    identifier: 0,              // 第几次触碰（触碰后不离开屏幕算同一次）
    position: {                 // 非固定摇杆的落点相对于屏幕位置
        x: 125,
        y: 95
    },
    force: 0.2,                 // 离原点的距离%，中心~大圆边=0~1,超过大圆外时,读数依然增加
    distance: 25.4,             // 离原点的距离in px，超过大圆外时读数不增加
    pressure: 0.1,              // 压力传感
    angle: {
        radian: 1.5707963268,   // 弧度0~2pi，以x轴正半轴为0
        degree: 90       //角度，以x轴正半轴为0度
    },
    instance: Nipple(object)    // the nipple instance that triggered the event 提供多个function和修改当前nipple参数的入口
    direction:{angle:"up",x:"right",y:"up"}//
}

【3】姿态解算

摇杆自带姿态解算，2类姿态：dir目前和plain预计，包含如下姿态：
dir:up\down\right\left,摇杆目前处在上下左右的位置触发
plain:up\down\right\left。摇杆逐渐向上下左右的位置移动触发
会触发不同的回调事件，通过listen注册可对不同姿态做出不同回应（结合data数据来量化姿态）。

joystick.on('start end', function (evt, data) {

    console.log(data);
}).on('move', function (evt, data) {

    console.log(data);
}).on('dir:up plain:up dir:left plain:left dir:down ' +
    'plain:down dir:right plain:right',
    function (evt, data) {

        console.log(evt.type);// 打印姿态text
    }
).on('pressure', function (evt, data) {
    console.log(evt.type);
});

【4】instance

Each joystick has the following signature :
每个joystick对象拥有一个instance属性，包含以下对象（所有的方法和属性都可以得到）。

{
    on: Function,
    off: Function,
    el: Element,
    show: Function,         // fade-in
    hide: Function,         // fade-out
    add: Function,          // inject into dom
    remove: Function,       // remove from dom
    destroy: Function,
    identifier: Number,
    trigger: Function,
    position: {             // position of the center
        x: Number,
        y: Number
    },
    frontPosition: {        // position of the front part
        x: Number,
        y: Number
    },
    ui: {
        el: Element,
        front: Element,
        back: Element
    },
    options: {
        color: String,
        size: Number,
        threshold: Number,
        fadeTime: Number
    }}