QApp 插件

简介

插件名称: ajax (适配 jQuery 风格，集成 jsonp 和 ajax

插件配置: {Object}

基本配置如下:

{
    "charset": "UTF-8",
    "timeout": 30 * 1000,
    "argsType": "query",
    "method": "get",
    "isEncode": false,
    "responseType": "json",
    "withCredentials": false
}

配置参数：

url: {String} 请求地址。
bizType: {String} 业务中默认参数设置。默认 false 。
charset: {String} 编码。默认 UTF-8 。
timeout: {Number} 请求超时时间。默认 30 * 1000 。
data: {Object} 请求参数。
argsType: {String} 请求参数类型。可选值：query 和 json。默认 query 。
method: {String} 请求方式。默认 get 。
headers: {Object} 请求头信息。
isEncode: {Boolean} 否是编码。默认 false 。
dataType: {String} 返回数据的数据类型。默认 json 。
cache: {Boolean} 是否允许缓存。默认 false 。
withCredentials: {Boolean} 是否带有验证信息。默认 false 。
jsonp: {String} 为 jsonp 请求重写回调函数名对应的 key。这个值用来替代在 url 中"callback=?"的"callback"部分。
jsonpCallback: {String} 为 jsonp 请求指定一个回调函数名。这个值将用来取代自动生成的随机函数名。
success: {Function} 请求成功后的函数调用。
error: {Function} 请求失败后的函数调用。
onAbort: {Function} 取消请求后的函数调用。
onFail: {Function} 请求失败后的函数调用。

添加的方法

QApp.ajax.setBizOptions(key, opt)

说明：设置业务的基本参数

参数：

key: {String|Object} 业务参数关键字。当key类型为字符串时，以key-value的形式进行设置；key类型为Object时，将对象作为参数对象进行添加
opt: {String|Undefined} 业务参数值

QApp.ajax.addMock(key, mock)

说明：mock数据

参数：

key: {String|Object} key类型为String时，为mock数据的关键字；key的类型为Object时，表示mock数据对象。
mock: {Object} mock数据

QApp.ajax.addReqFilter(filter)

说明：添加请求参数的过滤函数

参数：

filter: {Function} 过滤函数

QApp.ajax.removeReqFilter(filter)

说明：移除某个请求时的过滤参数

参数：

filter: {Function} 过滤函数

QApp.ajax.addRespFilter(filter)

说明：添加数据的过滤函数

参数：

filter: {Function} 过滤函数

QApp.ajax.removeRespFilter(filter)

说明：移除数据的过滤函数

参数：

filter: {Function} 过滤函数

使用示例

// 在defineView时，plugins 内添加 ajax
// 正常的 ajax 请求
var ajaxDeferred = self.ajax({
    url: requestURL
}).done(function (data) {
    // TODO
}).fail(function () {
    // TODO
}).all(function (){
    // TODO
})


// 取消
ajaxDeferred.trans.abort()

本地mock数据

QApp-plugin-ajax 插件提供本地 mock 数据的功能，使用方法:

// 添加 mock 数据方式
// QApp.ajax.addMock("key", data); or
QApp.ajax.addMock({
    "key" : data
});

self.ajax({
    mockKey: "key",
    mock: true,
    url: requestURL
}).done(function (data) {
 // TODO
});

添加过滤函数

// 添加请求过滤函数
QApp.ajax.addReqFilter(function(opt, deferred) {
    // 如果通过 view.ajax 方式使用 ajax，
    // 通过以下方式获取 view
    // opt.__view
})


// 添加数据过滤函数
QApp.ajax.addRespFilter(function(data, err, opt, deferred) {
    if (err) {
        switch(err.type) {
            case 'Timeout':
                // 超时
                break;
            case 'Abort':
                // 取消
                break;
            case 'Fail':
                // 失败
                break;
            default:
                // 其他。目前只有上面三种出错情况
        }
    }
})

简介

插件名称: artTemplate

重写或添加的方法

添加的方法 renderData(key, data, container, appendType)

Param key: {String} 关键字
Param data: {Object} 渲染数据
Param container: {String} node的选择器
Param appendType: {String} 插入位置设置，值为beforebegin(插入目标节点前)、afterbegin(插入到目标节点的第一个子节点前)、inner(替换目标内子元素)、beforeend(插入到目标节点的最后子节点之后)、afterend(插入到目标节点之后)

示例

QApp.defineView('name' {
    html: '<p>{{name}}</p>',
    plugins: [{
        name: 'artTemplate',
        options: {
            global: {
                data: {'name': 'david'}
            }
        }
    }]
});

// 动态渲染
QApp.defineView('pageA.pageA-1', {
    html: html,
    plugins: [{
        name: 'artTemplate',
        options: {
            key: {
                template : tpl,
                container : '[node-type=hoganContainer]',
                appendType : 'inner'
            }
        }
    }],
    init: {
        myFunc: function() {
            this.renderData('key', { // render data
                data: data
            });
        }
    }
});

简介

插件名称: avalon

插件配置：Function 或者 Map<String, Function>

当配置为 Function 时，则是一个 factory，然后以 View 的 root 为根节点，并在其上自己添加 ms-controller ，并 scan。
当配置为 Map 时，则是多个 factory ，相应的key 则是其id，需要用户自己在模板上添加 ms-controller。

注：

avalon 的 factory 没有绑定 context (this)。
插件将 context (this) 设置成当前的 View 实体。

示例:

{
    name: 'avalon',
    options: function(vm) {
        //TODO
    }
}

在 View 的 extra 配置中配置 vmcache 可开启 vm 缓存功能。

重写或添加的方法

添加的方法: getVM(key)

Param key: {Undefined|String} 关键字
Return {VModel}
当包含单一的 vm 时，用 getVM() 获取；如果是包含多个 vm 时，用 getVM(key)，key 为 vm 的 id。

重写的方法: mergeParam(newParam)

逻辑和原来一样，增加了更改 vm 的逻辑。

重写的方法: destory()

和原来逻辑一样，增加了序列化保存 vm 的逻辑。

其他事宜

重写了 QApp.addWidget 方法，对于此方法的说明，详见 widget.md。

作用是，将注册到 QApp 的组件，同时注册到 avalon 组件内。可以使用 ms-widget=qapp-组件名 的形式调用，主要解决，avalon 的 vm 更改，影响到 Dom 增添时，会触发组件的逻辑。

简介

插件名称: basic

基础插件组，主要用于视图的展现效果，通过 open 和 show 中配置 ani 使用，其中包括 dialog, actionSheet, popup 三个动画插件。

PS: moveEnter 插件放到 QApp 核心包内，作为默认效果。

MoveEnter 插件说明

插件名称: moveEnter

插件配置：{Object}

基本配置如下:

{
    "autoHide": true,
    "position": "right",
    "distance": 0,
    "duration": 300
}

配置参数：

autoHide: {Boolean} 是否自动隐藏。默认 true 。
position: {String} 从何方移入。默认 right 。可能的值 right | left
distance: {Number} 移入距离。默认 0。（如果为 0，自动获取视图的对应尺寸作为 distance，当 App 的 type 为 mobile 时，默认全屏尺寸）
duration: {Number} 动画效果时长。默认 300。

重写或添加的方法

重写 show 和 hide 方法，两个方法均没参数。

Dialog 插件说明

插件名称: dialog

插件配置：{Object}

基本配置如下:

{
    "autoHide": false,
    "maskColor": "#000",
    "maskOpacity": "0.4",
    "duration": 200,
    "width": 0,
    "height": 0
}

配置参数：

autoHide: {Boolean} 是否自动隐藏。默认 false 。
maskColor: {String} 蒙层颜色。默认 #CCC 。
maskOpacity: {String} 蒙层透明度。默认 0.5。
duration: {Number} 动画效果时长。默认 300。
width: {Number} dialog 宽度。默认 0。（如果为 0，自动获取视图的宽度）
height: {Number} dialog 高度。默认 0。（如果为 0，自动获取视图的高度）

重写或添加的方法

重写 show 和 hide 方法，两个方法均没参数。

插件名称: popup

插件配置：{Object}

基本配置如下:

{
  "autoHide": true,
  "autoDirection": true,
  "direction": "right",
  "duration": 100,
  "width": 0,
  "height": 0,
  "position": "center"
}

配置参数：

autoHide: {Boolean} 是否自动隐藏。默认 true 。
autoDirection: {Boolean} 自动选择方向。默认 true 。
direction: {String} 从何方移入。默认 right 。可能的值 right | left | top | bottom
duration: {Number} 动画效果时长。默认 100。
width: {Number} popup 宽度。默认 0。
height: {Number} popup 高度。默认 0。
position: {String} 上下显示时的居中情况。默认 center 。可能的值 center | right | left

重写或添加的方法

重写 show 和 hide 方法，show方法有参数，要指定显示时相对应的 element。

ActionSheet 插件说明

插件名称: actionSheet

插件配置：{Object}

基本配置如下:

{
  "autoHide": true,
  "distance": 0,
  "duration": 200,
  "showMask": true,
  "maskColor": "#000",
  "maskOpacity": "0.4"
}

配置参数：

autoHide: {Boolean} 是否自动隐藏。默认 false 。
distance: {Number} 移入距离。默认 0。
duration: {Number} 动画效果时长。默认 200。
showMask: {Booleamn} 是否显示蒙层。默认 true。
maskColor: {String} 蒙层颜色。默认 #000 。
maskOpacity: {String} 蒙层透明度。默认 0.4。

重写或添加的方法

重写 show 和 hide 方法，两个方法均没参数。

添加 refresh 方法，在 view 高度发生变化时刷新 view。

简介

插件名称: delegated

插件配置：{Object}

默认配置如下:

{
    "tag": "action-type",
    "eventType": "tap"
}

配置参数：

tag: {String} 监听DOM中具有action-type属性的节点。
eventType: {String} 事件类型，默认为tap事件。

重写或添加的方法

添加的方法: bind(action, eventType, process)

Param action: {String} 监听关键字
Param eventType: {String|Function} 事件类型或处理函数
Param process: {Function} 处理函数
Return {Undefined}

示例

QApp.defineView('name' {
    html: '<p action-type="abc" data-arg="xyz">Some</p><p action-type="def" data-arg="xyz">Any</p>',
    plugins: [{
        name: 'delegated',
        options: {
            tag: 'action-type',
            eventType: 'tap'
        }
    }],
    ready: function() {
        this.bind('abc', function(e, data) {
            // data.arg === 'xyz'
        });
    },
    bindActions: {
        'def' : function(e, data) {
            // data.arg === 'xyz'
        }
    }
});

简介

插件名称: doms

配置参数：

tag: {String} 查找DOM中具有相同属性的节点，并建立以值建立映射。默认为 node-type。

说明：

通过 view.doms 访问属性为 tag 的节点。

重写或添加的方法

添加的方法: find(type)

Param type: {String} node-type属性值

在 view 的 ready 事件阶段后，可以通过view.find方法快速访问 node 节点。

示例

QApp.defineView('name' {
    html: '<p node-type="abc">Some</p>',
    plugins: [{
        name: 'doms',
        options: {
            tag: 'node-type'
        }
    }],
    init: {
        pHandler: function(event) {
            // this.doms.abc === <p/>
        }
    },
    ready: function() {
        var p = view.find('abc'), // p === <p />
            self = this;
        p.addEventListener('tap', self.pHandler, false)
    }
});

简介

插件名称: fastclick (移动端快速点击)

说明

在视图 View 展现时，给视图增加 fastclick 机制。

简介

插件名称: gesture (手势库)

说明

现在支持轻触(tap)，双轻触(doubletap)，长按(press)，快滑(flick)，滑动(pan)。

扩展支持双指缩放(pinch)。

事件名和参数

对于每个事件，事件对象里都有以下属性：screenX， screenY， clientX， clientY， pageX， pageY。

轻触：tap
双轻触：doubletap
长按：press、pressend
触摸：feel
轻滑：flick | 拓展属性：offsetX、offsetY、speedX、speedY、duration、degree、directions
滑动：pan、panend | 扩展属性：offsetX、offsetY、degree、directions | panend 包含扩展属性： speedX、speedY、duration
缩放：pinch、pinchend | 扩展属性：scale

事件触发说明：

tap / doubletap / press / feel 触按事件

用户触碰屏幕，并且位移距离小于 10，则会判定为触按事件。
用户开始触碰屏幕和结束触碰直接时差小于 200ms ，则会被判定为tap事件，反之被判定为press事件。
tap和press事件 不会被同时触发 。
如果两次tap事件的时间差小于 500ms，则会被判定为doubletap事件。
doubletap事件和tap事件 会同时触发，doubletap会在第二次tap事件之前触发。
feel即触即触发，和tap、press并行。

flick / pan 滑动事件

用户点击屏幕，并且位移距离大于 10，则会判定为滑动事件。
用户开始触碰屏幕和结束触碰直接时差小于 300ms ，则会被判定为flick事件。
flick和press事件 会被同时触发 。
flick会在pressend事件之后触发。
degree属性基准为水平向右坐标轴，顺时针方向，单位是角度。
directions为滑动方向，为一个数组：
- 元素值为：up、down、left、right；
- 第一个元素为 主方向，第二个元素是 副方向；
- 当实际方向与主方向的夹角小于 15度 时，不存在副方向。

pinch 缩放事件

用户双指点击屏幕，并且移动，直接距离变化量大于 10，则会判定为缩放事件。

globalContext

简介

插件名：globalContext

全局工具类插件，本地存储组件。本插件提供两种版本的本地存储，请根据使用环境选择。

使用方式

1. 直接使用localStorage

QApp.util.storage(key[, value])

说明：存/取/删除单条数据

获取数据：只有 一个参数 时，为get方法。
设置数据：有 多个参数 时，为set方法；第二个参数 value 支持任何类型的值。
删除数据：value 为 undefined 或 null 为删除操作。

QApp.util.storage.clear();

说明：清除所有数据

2. 使用globalContext

使用场景：

SPA/多webview项目里，数据传递、数据共享等运行时数据。

注意事项：

该种存取数据的方法来源于SPA项目：在一个页面中，经常有一些运行时数据来进行数据传递或共享，所以是存放在内存中的。但是，到了大客户端/独立客户端的 多webview 时代， webview之间无法共享内存，所以在webview之间这些运行时数据需要通过localStorage来进行中转。即：这些数据在单个webview/SPA内还是存储在内存中，而在页面之间，通过localStorage将这些数据重新同步到不同的内存中。之所以没有用localStorage来直接取代内存，是因为ls的读写是阻塞式的读写文件，对于一些存取频繁的数据进行操作，效率还是较差。

重要：在多webview环境时，需要在初始化的时候，通过 QApp.util.globalContext.addLocalKeys 来指定哪些数据是需要在webview之间传递的，本插件会自动来进行数据同步。

QApp.util.globalContext.addLocalKeys(key)

说明：添加需要在webview之间同步的数据的key

QApp.util.globalContext.set(key, value)

说明：设置数据

QApp.util.globalContext.get(key)

说明：获取数据

QApp.util.globalContext.merge(key, value)

说明：merge数据

QApp.util.globalContext.remove(key)

说明：删除一条数据

QApp.util.globalContext.clear(key)

说明：清空所有数据

简介

插件名称: hogan

插件配置：{Object|Function}

当为 Function 时，执行结果为配置，并且方法 context 为此视图 View 示例。
配置有两个属性, data 为模板数据，options 为 hogan 配置。

重写或添加的方法

添加的方法 renderData(key, data, hoganOpt, container, appendType)

Param key: {String} 关键字
Param data: {Object} 渲染数据
Param hoganOpt: {Object} 参数对象
Param container: {String} node的选择器
Param appendType: {String} 插入位置设置，值为beforebegin(插入目标节点前)、afterbegin(插入到目标节点的第一个子节点前)、inner(替换目标内子元素)、beforeend(插入到目标节点的最后子节点之后)、afterend(插入到目标节点之后)

示例

QApp.defineView('name' {
    html: '<p>{{name}}</p>',
    plugins: [{
        name: 'hogan',
        options: {
            global: {
                data: {'name': 'david'}
            }
        }
    }]
});

// 动态渲染
QApp.defineView('pageA.pageA-1', {
    html: html,
    plugins: ['hogan'],
    hoganOptions: {
        // 模板配置
        key: {
            template : tpl,
            container : '[node-type=hoganContainer]',
            appendType : 'inner'
        }
    },
    init: {
        myFunc: function() {
            this.renderData('key', {
                data: data // hogan data
            });
        }
    }
});

简介

插件名：scroll （同时包含scroll组件）

说明：滚动插件，对 iScroll 进行封装，包含 nScroll 和 avalon.iscroll，并包括 scroll 组件。

QApp 中滚动依赖库为 iScroll，版本是 probe 5.1.3 版，文档 iscrolljs.com。

希望使用 scroll 的同学可以了解一下 iscroll，这个组件是世界上最好的前端滚动组件，没有之一。

这里列一下 iscroll 必须 注意 的问题：（一般情况）

滚动的父容器，同时也是 iScroll 配置的第一个参数 el，此元素必须是 可单独计算高度 的，也就是不依赖于内部元素的。（当然你横向滚动时，需要的是宽度）
父容器应该是 overflow:hidden 的，这样可以显示成内部区域可滚动。
父容器需包含一个子节点container用来滚动，这是 iScroll 约定的，这个节点的size是滚动计算的依据。

对于目前业务中的可动态加载的大列表，进行了优化，添加了懒加载功能。使用的是基于iscroll自己编写的nscroll组件。

如何使用

最常用的方式是通过组件的方式。

开发者可以用在父容器上添加 qapp-widget="scroll" 的方式使用，此时父容器需要定高。

有关Avalon

由于业务中多使用 avalon ，所以自己额外开发了avalon.iscroll组件。

对于avalon.iscroll的说明如下：

添加 ms-iscroll 命令，值为 id, opt, 和avalon.oniui类似。

如果使用加载功能：

dom 需要结构与 iscroll 相同，因此，孙子节点应该是ms-repeat元素。
因为要计算位置，所以每个元素的初始位置都应该是(0, 0)，不论怎么实现（absolute或使用margin进行偏移）。
在定义vm时，如果是循环元素是list，那么需要用户主动添加僵尸元素list$。

简介

插件名：zepto

引入插件，方便开发者快速、方便引用 zepto，并解决手势冲突问题

QApp Framework 插件

ajax

简介

添加的方法

使用示例

本地mock数据

添加过滤函数

artTemplate

简介

重写或添加的方法

示例

avalon

简介

重写或添加的方法

其他事宜

basic

简介

MoveEnter 插件说明

重写或添加的方法

Dialog 插件说明

重写或添加的方法

Popup 插件说明

重写或添加的方法

ActionSheet 插件说明

重写或添加的方法

delegated

简介

重写或添加的方法

示例

doms

简介

重写或添加的方法

示例

fastclick

简介

说明

gesture

简介

说明

事件名和参数

事件触发说明：

tap / doubletap / press / feel 触按事件

flick / pan 滑动事件

pinch 缩放事件

globalContext

简介

使用方式

1. 直接使用localStorage

2. 使用globalContext

hogan

简介

重写或添加的方法

示例

scroll

简介

如何使用

有关Avalon

zepto

简介

相关