概述

KK JS-SDK是基于移动KK平台的Web应用开发工具包。

Web应用开发人员使用KK JS-SDK,可以调用拍照、拨号、定位等的移动设备能力,可以访问移动KK自身通讯录,可以对文件进行查看、删除、压缩/解压、加密/解密等操作,为KK用户提供更好的网页体验。

此外,KK JS-SDK还能部分兼容基于微信平台开发的Web应用,详见兼容微信的能力模块

KK JS SDK版本变更记录请参考 Changelog.

整体说明

关于文档

此文档有下面几条约定:

1.函数原型中,被方括号包裹的参数为可选参数.

如: kk.app.callNativeApp(options, [done], [fail]) 这里的done、fail都是可选参数

2.参数类型 Any 表示参数的类型可以是javascript支持的任意数据类型
3.文档中所有涉及分辨率、尺寸或者宽高的单位都是像素(px)

kk.app.getDeviceInfo 获取到的分辨率,kk.media.getPicture 中设置图片的宽高等

文件路径

API中文件路径有以下几种写法:

协议 路径位置
app 应用包自身。如 app://doc/myfile.doc 表示应用包 中的 doc 文件夹中的 myfile.doc 文件
public KK客户端公共存储区。如 public://temp/ 表示公共存储区 temp 文件夹
sdcard Android指向sd卡,iOS则指向KK客户端的 document 文件夹。如 stcard://message.wav 在Android机器上表示sd卡根目录下的 message.wav 文件,在iOS上表示KK客户端 document 目录下的 message.wav 文件

调用说明

所有能力通过kk对象来调用 (若有命名冲突,使用kk.noConflict来解决命名冲突)。

KK JS SDK中大部分能力均为异步的能力,即需要使用回调函数才可知道能力的执行结果,只有极少部分能力会直接返回结果。异步调用的能力都有可以传入成功回调和失败回调,其中:

  • 成功回调可能会接收一个对象作为参数。读取类型的能力,成功回调函数是必传的,比如 拍照,录音,选择通讯录联系人;其他类型的能力成功回调选填.
  • 失败回调都会接收两个参数fail(code,msg),code为错误代码,msg为错误说明。一般能力调用参数参数错误,客户端无相应权限(如用户未授权客户端使用摄像头,则无法使用拍照及录视频的能力),用户取消操作(如取消拍照)等均会进入失败回调。失败回调均为选填。

公用的错误代码

KK客户端提供的应用能力,在调用失败的情况下,会调用到应用提供的失败回调函数,返回错误码给应用。这里罗列一些公用的错误码。

错误代码 描述
999 能力发生了未知的错误。
998 能力未定义。
996 未授权的能力调用。
990 非法能力调用。

使用步骤

获取并引入JS SDK

使用传统的方式下载源码并引入

步骤1. 获取JS-SDK文件,点此获取JS-SDK文件

步骤2. 引入JS-SDK文件,通过 <script> 标签或者使用 AMD/CMD 标准模块加载方法加载。

@section('加载方式1: 标签加载')
<!--Script标签加载:-->
<script src='kk-1.2.43.js'></script>
@endsection
@section('加载方式2: CMD加载')
// 对CMD加载工具进行配置,此处使用seajs
seajs.config({
  base: "../sea-modules/",
  alias: {
    'kk': 'app/kk-1.2.43.js'
  }
});


// 在模块代码中即可这样使用:
define(function(require){
    // 引入KK
    var kk = require('kk')
    // 监听ready事件,即可在回调中使用kk的API
    kk.ready(function(){
        // 调用能力
    })
})

@endsection
@section('加载方式3: AMD加载')
//AMD加载:
requirejs(['jquery', 'app/kk-1.2.43'],function($,kk){
  // 监听ready事件,即可在回调中使用kk的API
  kk.ready(function(){
    // 调用能力
  })
});
@endsection
@section('在EKP项目中加载JS SDK')
// 声明依赖内置的KK JS SDK
define(['mui/device/kk5/kk5'],function(kk){
  //监听ready事件,即可在回调中使用kk的API
});
@endsection

配置并使用

步骤3. 配置JS-SDK(可选)

@section('配置JS-SDK')
//步骤2:配置JS-SDK(可选)
//  配置应用,输出能力调用的详细日志, 推荐开发时开启该选项
kk.config('detailLog', true);
@endsection

步骤4. 监听ready事件,回调后即可使用kk的API

@section('监听ready事件,回调后即可使用kk的API')
//步骤3:监听ready事件,回调后即可使用kk的API
//应用运行入口:
kk.ready(function(){
  //调用kk的API
});
@endsection

核心入口模块

kk入口模块,整个库的核心入口模块,定义的库的命名空间kk(以及别名 Easymi,为兼容旧有项目),并暴露给全局使用。

提供了 kk.readykk.noConflict 两个核心方法。

kk.ready(fn)

将函数添加到 native 初始化后的回调函数队列,可以多次调用。 若调用 ready 时,native 已完成初始化,则立即执行传入的函数。

fn(args)

类型: function
接收一个对象args作为参数, 这个对象 args 描述了应用启动时的相关信息。

args.netState

类型: number
网络状态:0:离线,1:在线

args.startType

类型:number
应用的启动类型:

  • 1:用户请求使用应用
  • 2:被推送消息拉起
  • 3:被其他应用拉起

args.callArgs

类型 object
调用参数,startType 等于2时,为推送消息的数据;等于 3 时,为调用参数(第三方应用穿入的参数)。

@section('监听ready事件示例代码')
//监听ready事件
kk.ready(function( args ){
    /*args值示例
    {   
        startType:'1',
        netState:'0',
        callArgs:{}
    }
    */
    var type = args.startType;
    if(type === 1){//用户请求使用应用
        //相应操作
    }else if(type === 2){//被推送消息拉起
        //相应操作
    }else if(type === 3){//被其他应用拉起
        //相应操作
    }
});
@endsection

kk.noConflict()

解决命名冲突,将全局命名空间下的 kk 改回 加载KK SDK 之前的值. 如果在加载 KK SDK 之前已经存在一个名字为 kk 的变量,执行 kk.noConflict() 后会返回JS SDK能力对象,变量kk 将恢复为加载KK SDK 之前的值。

@section('解决命名冲突示例代码')
// 假设 kk 加载之前已经存在一个 kk 变量
var kk = {
    name:'kk'
};

// 加载KK后,修改kk的命名,将 kk 值改为加载JS SDK之前的值
var newkk = kk.noConflict();
newkk.ready( function(){
    //使用newkk来调用kk的API
});

console.log( kk.name );  //=> 'kk'
@endsection

kk.isKK()

判断当前Web应用的运行环境是否为移动KK客户端,若为kk移动客户端,则返回 true。该能力通过检测浏览器的userAgent 中是否有 kkPlus 来判断。

@section('判断运行环境是否为KK')
if( kk.isKK() ) {
    alert('Welcome kk user!');
}
@endsection

kk.defy(fn, [[args1], ...[, argsN])

将KK的能力函数 promise 化, 可以使用链式调用的方式传递能力的回调函数

fn

类型: function|string, 必填

  • function: KK能力函数(如kk.media.getPicture),
  • string: 能力名称(如"media.getPicture", "app.getNetState")

argsN

类型:any
能力函数的参数中除了回调函数(包括成功回调和失败回调)的其他参数, 可以有多个

  • 如果调用的能力一定要传参数,则 argsN一定要传
  • 如果调用的能力参数是可选的,则 args也是可选的;

返回值

类型: object
调用该函数后返回一个promise对象, 支持以下promise写法:

  • then(done, fail), 可接收能力的成功回调和失败回调
  • done(done), 可接收能力的成功回调
  • fail(fail), 可接收能力的失败回调
  • catch(fail), 同 fail(fail)
  • finally(fn), 不论能力执行成功或者失败,均会执行回调函数 fn
  • always(), 同 finally(fn)

返回的promise 对象的的回调函数接收的参数与被promise化的能力是一致的。

成功回调写在then函数第一个参数或者done函数里面,失败回调写在then函数第二次参数或者fail函数或者catch函数里面,其它函数用法请查看promise的用法

@section('带参数的,有成功回调,失败回调的')
//调用获取图片能力
kk.defy(kk.media.getPicture, {
  sourceType: 'album'
}).then(function(res){
  // 成功回调
  /*
    {
      imageURI: "sdcard://easymi/1496399648439.png", 
      imagePath:  "kkapp://fil.o-1207-o.kk/storage/sdcard1/easymi/1496399648439.png", 
      imageTime: Fri Jun 02 2017 18:34:07 GMT+0800 (CST), 
      imageFileOSPath:  "kkapp://fil.o-1207-o.kk/storage/sdcard1/easymi/1496399648439.png", 
      imageTimeString: "20170602183407"
    }
   */
  console.log(res);
}).catch(function (code, msg) {
  console.log('获取照片失败,错误代码是' + code + '错误信息是' + msg) ;
}).finally(function () {
  console.log('能力执行完成')
})

//等同于 =>

kk.defy('media.getPicture', {
  sourceType: 'album'
}).then(function(res){
  // 成功回调
  console.log(res);
}).catch(function (code, msg) {
  console.log('获取照片失败,错误代码是' + code + '错误信息是' + msg) ;
})
@endsection

@section('无参数,只有成功回调的')
// 获取当前角标
kk.defy(kk.app.getBadge).then(function(res) {
  // 成功回调
  /*
    Object {num: "0"} 
   */
  console.log(res);
})
@endsection

@section('无参数,只有失败回调的')
// 返回上一页
kk.defy(kk.history.back).catch(function() {
  console.log('当前页不能做返回操作');
})

@endsection

@section('无参数,无成功和失败回调的')
// 获取当前网络状态
kk.defy('app.getNetState').then(function(res) {
  /*
    Object {netState: 0} 
  */
  console.log(res);
})

@endsection

应用配置模块

kk.config

获取或设置应用配置。目前仅支持应用的日志配置。

在KK中,如果有应用使用 console.logconsole.debugconsole.errorconsole.warn 打印日志,日志不仅会在浏览器调试工具(比如 Chrome的 DevTools)中看到,还会输出到日志文件中,可在手机磁盘上查看到

支持的配置项

debug

类型: boolean, 默认为 true
是否调用能力打印日志(使用console.debug打印日志),日志会输出到日志文件中。该选项仅会打印能力调用的日志: 使用什么参数调用了什么能力,能力是否调用成功(成功回调接收的参数不会打印), 是否失败(失败信息会打印出来)。

detailLog

类型:boolean, 默认为 false
是否在日志中打印能力调用成功回调接收的所有参数, 只有 debugtrue 是,detailLog 的设置才有效。能力调用的成功回调参数可能会带有敏感信息(比如 kk.proxy.request 的成功回调接收的参数则是后台接口返回的数据),建议仅在开发阶段开启该选项,方便调试能力的详细调用情况。

日志文件在手机上的位置

KK管理台->应用管理->移动端应用上添加手机移动web应用之后,会得到一个应用ID,在手机上日志文件的名称即以该ID命名。

在管理台查找应用ID

Android和iOS的日志在手机上路径是不一样的。

Android日志文件位置

[Andorid内部存储空间]/Andorid/data/com.landray.kkplus/files/log/applog/ 目录下以 应用ID命名(无文件后缀)的文件,该文件为纯文本文件,可用任何能打开纯文本文件的软件查看。路径中的com.landray.kkplus是客户端的包名,不同企业定制的客户端使用的包名可能有所不同,需与KK产品部出包人员确认Android客户端的包名

iOS日志文件位置

查看iOS的日志必须借助iTunes。在电脑上安装iTunes后,使用数据线连接iOS设备,在iTunes中点击已连接的iOS设备,管理其中的应用,在 文件共享 下找到 KK 5.0(企业定制的客户端则会是企业自定义的名称) 并选中它,在右侧 KK 5.0的文稿列表中即可找到 以应用ID命名(文件后缀为 .log)的文件,该文件为纯文本文件,将其拖拽至电脑上,即可使用文本编辑器查看。

查看iOS日志

获取应用的配置 kk.config([key])

获取应用的配置。keystring 即配置项键名。如果不传入 key, 则返回一个对象,包含所有配置项。若传入 key 则返回该 key 对应的值。

@section('设置和获取应用配置:不传参数')
// 1.不传参数:返回包含所有配置的对象
var appConfig = kk.config();
console.log(JSON.stringify( appConfig ) );
//=>'{"debug": true, "detailLog": false}'
@endsection
@section('设置和获取应用配置:传入一个配置键名字符串')
// 2.传入一个配置键名字符串:返回键名对应的值
var appConfig = kk.config( 'detailLog' );
console.log( appConfig );
//=>false
@endsection

设置应用的配置

可以通过 kk.config(options) 设置多个配置项的值(options为对象). 如果options中的属性名在配置项中存在,则修改 options 中的值,完成后返回全部配置项

也可以通过 kk.config(key, value) 设置单个配置项的值。将配置项 key 的值设置为value,并返回value

@section('设置和获取应用配置:传入两个参数(key,value)')
// 3.传入两个参数(key,value):返回设置的值
var appConfig = kk.config( 'detailLog', true );
console.log(appConfig);
//=>true
@endsection
@section('设置和获取应用配置:传入一个对象')
// 4.传入一个对象:返回包含所有配置的对象
var appConfig = kk.config({
    debug: false
});
console.log( JSON.stringify( appConfig ) );
//=>'{"debug": false, "detailLog": false}'
@endsection

应用模块

app模块,提供了控制app的基础能力,如应用退出、拉起引用、监听应用事件、应用徽章控制等等

kk.app.exit()

退出Web应用:直接关闭Webview窗口,该能力无返回值。

@section('退出应用示例代码')
//退出应用
kk.app.exit();
@endsection

kk.app.isOfflineApp()

判断当前应用是否为混合应用, 若为混合应用则返回 true ,否则返回 false

@section('判断当前应用是否为混合应用')
var flag = kk.app.isOfflineApp();
if (flag) {
  console.log('当前应用为混合应用');
} else {
  console.log('当前应用不是混合应用');
}
@endsection

kk.app.callApp

调用客户端内置的其他Web应用。
该能力有两种调用方式:

  • kk.app.callApp(appInfo, [done], [fail])
  • kk.app.callApp(appInfo, args, [done], [fail])

appInfo

类型:objectstring
被调用的Web应用的应用信息。

appInfo 为对象时

可携带下述信息:

  • appInfo.url: string类型, 应用的启动URL,即被拉起应用的访问地址(仅支持http及https协议)
  • appInfo.code: string类型, 应用代码,可在KK管理台上查看(在KK管理台增加移动Web应用时填入的应用代码)。若要启动混合应用,则只能通过应用代码打开

以上信息可二选一,亦可都提供:

  • 若只提供 appInfo.code, 客户端则会在新窗口打开该应用代码的 web 应用
  • 若只提供了 appInfo.url, 客户端则会在新窗口中打开该URL
  • 若二者均提供了,客户端则会在新窗口打开 appInfo.url 指定的URL,并使用 appInfo.code 对应应用参数(应用的参数主要影响代理模块的能力,使用该模块的能力需要在KK管理台上进行相应配置). 所以打开应用时, appInfo.codeappInfo.url 应当相对应,否则可能导致代理相关的能力异常(请求地址错误,上传下载地址错误)。

appInfo 为字符串时

appInfo 为URL,则相当于上述结构中的 appInfo.url, 否则当作 appInfo.code 处理。

appInfo.code(应用代码) 可在 KK管理台->应用管理->移动端应用->移动混合应用管理 上找到该手机移动web应用,就会得到它的 应用代码

在管理台查找应用代码

args

类型: any(null, number, string, boolean, array, object)
在第一种调用方式下不填,在第二种调用方式下必填。传递给被拉起应用的参数,被拉起应用可以在其应用内部的 kk.ready的回调函数中的 args.callArgs 拿到该参数并进行相应处理。

done()

类型: function ,可选
调用成功后即会执行,该函数不接受参数。

fail(code, msg)

类型: function ,可选
调用失败后即会执行,该函数不接受参数。code 类型为number, msg 为错误代码

使用应用代码拉起应用示例

@section('使用应用代码拉起应用')
// 拉起混合应用 日程管理
// KK-SCHEDULE 为 KK 日程管理 应用的应用代码
kk.app.callApp( 'KK-SCHEDULE', function(){
  // 拉起后,本应用退出。
  kk.app.exit();
}, function( code, msg ){
  console.log('kk.app.callApp 错误代码:' + code + ' , 错误信息:' + msg );
});
@endsection


@section('使用应用代码拉起应用, 并传入相关参数')
// 拉起混合应用 日程管理
// KK-SCHEDULE 为 KK 日程管理 应用的应用代码,并传入给日程管理应用传入参数 date
kk.app.callApp({
  code: 'KK-SCHEDULE'
}, {
  date: '2017-2-28'
}, function(){
  // 拉起后,本应用退出。
  kk.app.exit();
}, function( code, msg ){
  console.log('kk.app.callApp 错误代码:' + code + ' , 错误信息:' + msg );
});
@endsection

使用应用的访问地址拉起应用

@section('拉起在线应用示例代码')
// 打开 KK JS SDK的官网
kk.app.callApp('http://kk5.landray.com.cn:6789/jssdk');
@endsection

@section('拉起在线应用示例代码')
// 打开 KK JS SDK的官网
kk.app.callApp({
  url: 'http://kk5.landray.com.cn:6789/jssdk'
}, function(){
  console.log('应用拉起成功')
}, function( code, msg ){
  console.log('kk.app.callApp 错误代码:' + code + ' , 错误信息:' + msg );
});
@endsection

应用代码及访问地址均提供

@section('拉起应用示例代码')
// 打开 KK JS SDK的官网
kk.app.callApp({
  code: 'KK-SCHEDULE',
  url: 'http://ekp.landray.com.cn/sys/person/home.do?mod=timemanage'
});
@endsection

kk.app.callNativeApp(options, [done], [fail])

拉起原生应用,启动第三方native应用

options

类型: object
调用应用的参数,iOS和Android的参数不一致,详见options

options(iOS)

options(iOS).url

类型: string
Native应用注册处理的url
URL及URL上携带的参数需被拉起的 iOS 客户端开发商提供。

options(Android)

以下参数均可选,具体传递什么参数,需被拉起的android客户端开发商提供。

options(Andrid).url

类型: string
Intent Data url

options(Andrid).type

类型: string
Intent MimeType

options(Andrid).action

类型: string
Intent Action

options(Andrid).category

类型: string
Intent category,暂不支持多个

options(Andrid).package

类型: string
Intent package

options(Andrid).class

类型: string
Intent class

options(Andrid).otherParam

类型: object
拉起应用的额外参数,作为extra放到启动Intent中。

注意 otherParam 中的键值对中的键即为 extra 的 name,value 可以是:

  • 字符串
  • html字符串,因为html也是字符串,所以传递html时候需做特殊处理: 字符串前应追加 char code 为 128 的控制字符, JS SDK会自动处理。假设 value = '<h1>标题</h1>', 则应变为 value = String.fromCharCode(128) + value.
  • URL字符串,因为URL也是字符串,所以传递URL时候需做特殊处理: 字符串前应追加 char code 为 129 的控制字符, JS SDK会自动处理。假设 value = 'http://www.landray.com', 则应变为 value = String.fromCharCode(129) + value.
  • 数字(整型及浮点型)
  • 字符串数组(数组成员只能是字符串)
  • 整型数组(数组成员只能是整数)
  • 浮点型数组(数组成员只能是浮点数)

其他类型均不支持,由于 otherParam 是交由客户端处理(客户端使用java语言开发,强制类型),若参数类型错误均会导致调用能力失败。

done()

类型: function ,可选
成功回调

fail(code,msg)

类型: function ,可选 失败回调

错误代码 错误信息
9 没有对应的Native应用
@section('拉起原生发短信应用:Android示例')
// 拉起原生发短信应用:Android示例
kk.app.callNativeApp({
  action:"android.intent.action.SENDTO",
  category:"android.intent.category.DEFAULT",
  url:"smsto:13823794432",
  otherParam: {
    sms_body:"短信内容"
  }
}, function(){
  console.log('拉起原生应用成功');
}, function(code, msg){
  console.log('callNativeApp 错误代码:' + code + ' ,错误信息:' + msg );
});
@endsection
@section('拉起原生发短信应用:iOS示例')
// 拉起微信扫描二维码: iOS示例
kk.app.callNativeApp({
  url: 'weixin://dl/scan'//Native应用注册处理的url
}, function(){
  console.log('拉起原生应用成功');
}, function(code ,msg){
  console.log('callNativeApp 错误代码:' + code + ' ,错误信息:' + msg );
})
@endsection

kk.app.on(eventName, eventCB)

添加应用事件监听

eventName

类型: string
事件名称,详见可用的eventName如下表

事件名称 描述
pause 当应用被切换到后台运行时(可能是打开了其他应用或者按Home返回桌面),关闭时也会触发此事件
resume 当应用被切换到前台运行时执行,回调接收参数
exit 应用退出时,没有回调参数
netStateChange 客户端容器的网络状态变动时,回调接收参数
back 后退键事件,没有回调参数,可在事件回调中 return false 阻止返回行为,若有事件回调函数未及时 return false 操作,则仍会执行默认行为。
phoneStateChange 电话状态改变事件(Android Only),回调接收参数

eventCB

类型: function
事件回调,eventCB(args)的 args 参数为一个对象,不同的事件返回的args不同,详见各事件的args

当事件为resume时,事件回调args:

args.netState

类型: number
网络状态,0:离线,1:在线

args.startType

类型: number
触发类型,1:用户请求使用应用,2:被推送消息拉起,3:被其它应用调用拉起

args.callArgs

类型: object
调于用参数,startType等2时,为推送消息的数据,等于3时,为调用参数

当事件为netStateChange时,事件回调args:
args.netState

类型: number
网络状态,0:离线,1:在线

当事件为phoneStateChange时(仅在Android 下会触发),事件回调args:
args.phoneState

类型: number
电话状态,1:RING(响铃),2:OFFHOOK(摘机),3:IDLE(空闲)

args.param

类型: number
phoneState=1时,表示来电号码,其他无意义

@section('监听应用事务')
//监听应用事务
kk.app.on('resume', function( args ){
  if( args.netState == 0 ){//离线
    console.log('未连接网络,请检查网络');
  }else{//在线
    console.log('连接网络,可以执行请求');
  }
});
@endsection
@section('监听网络变化')
//监听应用事务
kk.app.on('netStateChange', function( res ){
  if( res.netState == 1 ){
    console.log('网络重新连接上');
    //更改网络标志为在线
  }else{
    console.log('网络断开' );
    //更改网络标志为离线
  }
});
@endsection

kk.app.setBadge(options)

设置应用徽章,在应用的入口图标的右上角显示一个数字。

options

类型: object
包含徽章值的对象,详见options

options.num

类型: number
要设置的徽章值,设置为0表示去除徽章

@section('设置徽章示例代码')
//设置徽章为"3"
kk.app.setBadge( {num: 3} );
@endsection

kk.app.getBadge(done)

获取应用徽章

done(args)

类型: function
成功回调,接收键名为num的对象作为参数,详见args

args:

类型: object
回调对象

args.num

类型: number
应用徽章的值

@section('获取徽章示例代码')
//获取应用徽章
kk.app.getBadge( function( res ){
  console.log( 'getBadge value: ' + res.num );
} );
@endsection

kk.app.getNetState()

返回网络状态 state 对象

state.netState

类型: number
网络状态值,1:在线,0:离线

@section('获取网络状态示例代码')
//获取网络状态 
var state = kk.app.getNetState();
if(state.netState == 1){
  console.log('网络在线');
}else{
  console.log('网络离线');
}
@endsection

kk.app.getDeviceInfo()

获取设备信息,如操作系统、设备类型、分辨率等。返回 deviceInfo 对象

deviceInfo.os

类型: string
操作系统,iOS/Android/windows(模拟器)

deviceInfo.type

类型: string
设备类型,phone/pad

deviceInfo.pixel

类型: string
分辨率,形如:1024x767(值较大的在前)

deviceInfo.largerPixel

类型: number
pixel属性中较大的一边

deviceInfo.smallerPixel

类型: number
pixel属性中的较小的一边

deviceInfo.deviceID

类型: string
设备物理唯一ID

@section('获取设备信息示例代码')
//获取设备信息
var deviceInfo = kk.app.getDeviceInfo();
/*deviceInfo 值示例
{
  os:'Andriod',//设备操作系统
  type:'phone', //设备类型               
  largerPixel:640,//分辨率
  smallerPixel:360,//分辨率中大的一边
  pixel:'640x360' ,//分辨率中小的一边
  deviceID:'58:1f:28:af:14:5d'//设备物理唯一ID
}
*/

@endsection

kk.app.getUserInfo()

获取用户信息,即登陆客户端的用户的账号信息,返回 userInfo 对象。

userInfo.userID

类型: string
用户id

userInfo.loginName

类型: string
用户登录名

userInfo.userName

类型: string
用户显示名称

@section('获取用户信息示例代码')
//获取用户信息 
var userInfo = kk.app.getUserInfo();
/*userInfo 值示例
{
  userID:'139',//用户id
  userName:'Johnson Wu',//用户登录名
  loginName:'wugh'//用户显示名称
}
*/

@endsection

kk.app.getAppInfo()

获取应用信息,返回 appInfo 对象

appInfo.appID

类型: string
应用ID

appInfo.name

类型: string
应用名称

appInfo.code

类型: string
应用代码

@section('获取应用信息示例代码')
//获取应用信息 
var appInfo = kk.app.getAppInfo();
 /*appInfo 值示例:
 {
  appID:'1091',//应用ID
  name:'测试''//应用名称
  code: 'mail 2.0', //应用代码
 }
 */
@endsection

kk.app.getClientInfo()

获取客户端信息,返回 clientInfo 对象

clientInfo.name

类型: string
客户端名称

clientInfo.version

类型: string
客户端的版本号(对外发布版本号, 包含版本号及发布时间等信息)

clientInfo.semver

类型: string
当前客户端的语义化版本号

clientInfo.innerVersion

类型:string
客户内部版本号(编译版本)

clientInfo.corpName

类型: string
企业名称

clientInfo.corpID

类型:string
企业ID

clientInfo.lang

类型:string
客户端语言。中文时该值为 zh-CN, 英文时该值为 en-US

clientInfo.webServer

类型:string
KK Web Server服务器地址,格式如 http://kk5.landray.com.cn。 KK Web Server 提供了KK相关的一些接口服务。

@section('获取客户端信息示例代码')
//获取客户端信息 
var clientInfo = kk.app.getClientInfo();
/*clientInfo值示例
{
  name:'kk', //企业客户端名称
  version:'v5.2.6.R.20170420,3',// 客户端版本号(对外发布版本号, 包含版本号及发布时间等信息)
  semver:'5.2.6',// 客户端的语义化版本
  corpName: '蓝凌科技', // 企业名称
  corpID:'1' // 企业ID
  innerVersion: 'v5.2.6.R.20170420,3' // 内部版本号(编译版本)
  lang: "zh-CN" //客户端语言 
  webServer: "http://kk5.landray.com.cn:8000" // 服务器地址
}
*/
@endsection

kk.app.getClientConfig(configName, done, [fail])

获取客户端配置

configName

类型: string
配置项名称,具体定义详见《配置项定义_客户端.xlsx

done

类型: function
成功回调,将结果直接返回在回调参数中

fail

类型:function ,可选
失败回调

// 具体配置项名称请联系相关人员获取
@section('获取kk服务器的地址')
//获取kk服务器的地址
kk.app.getClientConfig('kk_config_webserver_http_url', function (url) {
  console.log('服务器地址为: ' + url);
}, function (code, msg) {
  console.log('获取失败, 错误码: ' + code + ', 错误信息: ' + msg);
});
@endsection

kk.app.getAppIcon([appCode])

获取应用图标,返回 selfIconUrl 字符串。

appCode

类型: string ,可选
应用代码

@section('获取自身应用图标示例代码')
//获取应用图标url
//可获取应用代码相应的应用图标,若不传应用代码则为获取自身应用图标
var selfIconUrl = kk.app.getAppIcon();
console.log('自身图标url: ' + selfIconUrl);
@endsection
@section('获取应用图标示例代码')
//获取应用图标url
//可获取应用代码相应的应用图标,若不传应用代码则为获取自身应用图标
var appCode = 'ID333';
var iconUrl = kk.app.getAppIcon(appCode);
console.log('图标url: ' + iconUrl);
@endsection

kk.app.setCookie(options, [done], [fail])

给某个网址设置cookie,一般用于离线页面跳转至在线页面时设置用户身份验证信息

options

类型:object
包含url和cookie属性的对象

options.url

类型: string
cookie生效的域

options.cookie

类型: string
cookie字符串

done

类型: function ,可选
成功回调,没有回调参数

fail(code,msg)

类型: function ,可选
失败回调

错误代码 错误信息
999 cookie生效的域为空
@section('设置cookie示例代码')
//设置cookie
kk.app.setCookie({
  url: "http://192.168.1.187:7080/",
  cookie: "JSESSIONID=DD24DC2A1174E096DD9FD912C98D775A; Path=/; HttpOnly"
},function(){
  console.log('setCookie 成功');
});
@endsection

kk.app.getCookie(options, done, [fail])

获取某个网址中的cookie

options

类型: object
包含url属性的对象

options.url

类型: string
要获取cookie的url

done(args)

类型: function
成功回调,接收有cookie字符串属性的对象作为参数

args

类型: object

args.cookie

类型: string
获取到的cookie字符串

fail(code,msg)

类型: function ,可选
失败回调

错误代码 错误信息
999 参数url为空
@section('获取cookie示例代码')
//获取cookie
kk.app.getCookie({
  url: "http://192.168.1.187:7080/"
},function( res ){
  console.log('getCookie coolieStr: ' + res.cookie );
  //JSESSIONID=DD24DC2A1174E096DD9FD912C98D775A
});
@endsection

kk.app.captureScreen([options,] done, [fail])

应用截屏

options

类型: string ,可选,默认参数见下
配置参数,不传则全部使用默认参数

options.targetWidth

类型: number ,默认100px
输出图片宽

options.targetHeight

类型:number ,默认100px
输出图片高,需和targetHeight配合使用

options.encodingType

类型: string ,默认png格式
输出格式,可选值:jpeg/png

options.quality

类型: number ,默认为50
输出图片质量,范围:0-100,仅encodingTypejpeg时有效。数值越大,图片的质量越好,文件所占的存储空间越大。

options.destinationType

类型: string ,默认为data
输出形式,可选值:file/data

options.savePath

类型: number 保存路径,destinationType=file时有效,不指定时,以随机文件名保存到'sdcard://easymi/'文件夹

done(args)

类型: function
成功回调,返回一个对象作为参数,详见args

args.imageURI

类型:string
截屏后的文件保存路径(当destinationType为file时返回)

args.imageFileOSPath

类型:string
截屏后的文件的操作系统路径(当destinationType为file时返回)

args.imageData

类型: string
图片的base64编码(当destinationType为data时返回),可用作<img>标签的src属性

fail(code,msg)

类型: function ,可选
失败回调

错误代码 错误信息
-2 参数错误
@section('截屏:以文件形式输出')
//截屏:以文件形式输出
kk.app.captureScreen({
  encodingType: 'jpeg',
  quality: 80,
  destinationType: 'file',
  savePath: 'sdcard://capturescreen/' + new Date().getTime() + '.jpeg'
}, function( res ){
  /*res值示例
  {
    imageURI:'sdcard://capturescreen/1488268713915.jpeg',
    imageFileOSPath:'kkapp://fil.o-1091-o.kk/store/sdcard1/capturescreen/1488268713915.jpeg'
  }
  */
  //res.imageFileOSPath,可以作为<img>标签的src使用
  //res.imageURI,可以作为kk.media.save2album()的filepath,将相片保存到相册
  console.log('图片的保存路径:' + res.imageURI + ';图片的操作系统路径:' + res.imageFileOSPath);
});
@endsection
@section('截屏:以base64编码形式输出')
//截屏:以base64编码形式输出
kk.app.captureScreen({
  encodingType: 'jpeg',
  quality: 80,
  destinationType: 'data',
  savePath: 'sdcard://capturescreen/' + new Date().getTime() + '.jpeg'
}, function( res ){
  console.log('图片的base编码:' + res.imageData);
  //res.imageData 可以作为<img>标签的src使用
});
@endsection

kk.app.setScreenMode([mode])

设置屏幕显示模式, 默认值是 normal(普通模式),该能力无返回值

mode

类型: string ,可选
屏幕显示模式

可选值有:

  • normal 普通模式, 有kk导航栏,有系统状态栏。
  • enhanced 增强模式,隐藏kk导航栏,系统状态栏正常显示。
  • fullscreen 全屏模式,隐藏kk导航栏,但有系统状态栏,而且系统状态栏背景透明,不占用页面高度。
@section('普通模式')
// 普通模式
kk.app.setScreenMode('normal');
@endsection

@section('增强模式')
//增强模式 
kk.app.setScreenMode('enhanced');
@endsection

@section('全屏模式')
//全屏模式 
kk.app.setScreenMode('fullscreen');
@endsection

kk.app.showTitleBar()

显示应用容器(webview)的标题栏/导航栏,该能力无返回值。

@section('显示标题栏示例代码')
//显示标题栏
kk.app.showTitleBar();
@endsection

kk.app.hideTitleBar()

隐藏应用容器(webview)的标题栏/导航栏,该能力无返回值。

@section('隐藏标题栏示例代码')
//隐藏标题栏 
kk.app.hideTitleBar();
@endsection

kk.app.setTitle(title)

设置应用容器(webview)的标题栏/导航栏的标题,该能力无返回值。

title

类型: string ,可选
标题文字

@section('修改标题栏标题示例代码')
// 修改标题栏标题
kk.app.setTitle('个人信息');
@endsection

原生通讯录模块

设备通讯录模块,提供了操作客户端设别系统自带通讯录的能力

ContactInfo 联系人信息结构

类型: object
联系人信息,无需指定id信息

ContactInfo.id

类型: string
一个全局的唯一标识,可通过 find 方法获取到

ContactInfo.name

类型: string
名字

ContactInfo.namePY

类型: string
名字拼音/音标

ContactInfo.cname

类型: string
姓氏

ContactInfo.cnamePY

类型: string
姓氏拼音

ContactInfo.company

类型: string
公司

ContactInfo.phones

类型: array
联系人的电话号码列表,多个值之间用逗号分隔。
当phones为多个值时,每个位置的含义如下:

位置 含义
0 移动电话
1 住宅电话
2 工作电话
3 主要电话
4 住宅传真
5 工作传真
6 传呼
7 其他电话

ContactInfo.emails

类型: array
联系人的邮件地址列表,多个值之间用逗号分隔
当emails为多个值时,每个位置的含义如下:

位置 含义
0 电子邮件
1 工作邮件
2 个人邮件
3 主要邮件
4及以后 其他邮件

ContactInfo.addresses

类型: array
联系人的地址列表,多个值之间用逗号分隔
当addresses为多个值时,每个位置的含义如下:

位置 含义
0 主要地址
1及以后 其他地址

ContactInfo.firstLetter

类型: string
名字的首字母

ContactInfo.prefix

类型: string
前缀

ContactInfo.middleName

类型: string
中间名

ContactInfo.suffix

类型: string
后缀

ContactInfo.nickname

类型: string
昵称

ContactInfo.jobTitle

类型: string
职务

ContactInfo.department

类型: string
部门

ContactInfo.birthday

类型: string
生日

ContactInfo.notes

类型: string
备注

kk.contact.add(contactInfo, [done], [fail])

添加联系人
接收一个对象 contactInfo 作为参数, 这个对象描述了被添加联系人的相关信息,done 执行成功的回调, fail 执行失败的回调

contaceInfo

类型: object
联系人信息,无需指定id信息,详见上面 ContactInfo

done

类型: function ,可选
成功回调,没有回调参数

fail(code,msg)

类型: function ,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 操作失败
@section('添加联系人示例代码')
//增加联系人
kk.contact.add({
  'name':'Joyce',
  'phones':'13499997777'
}, function(){
  console.log('新增成功');
}, function(){
  console.log('新增失败');
});
@endsection

不带任何回调函数

@section('添加联系人示例代码')
kk.contact.add({
  'name':'John',
}); 

@endsection

kk.contact.remove(contactId, [done], [fail])

删除联系人
接收一个字符串 contactId 作为参数, 这个字符串为被删除联系人的Id,done 执行成功的回调,fail 执行失败的回调

contactId:

类型: string
联系人Id

done

类型: function,可选
成功回调,没有回调参数

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 操作失败
@section('删除联系人示例代码')
//移除联系人
kk.contact.find({
  'name':'Joyce.He',
  'phone':'13499997777',
}, function( res ){

  kk.contact.remove( res[0].id, function(){
    console.log('删除成功');
  }, function(){
    console.log('删除失败');
  });
}, function(){
  console.log( '需要删除的联系人不存在' );
});
@endsection

kk.contact.update(contactInfo, [done], [fail])

修改联系人信息 接收一个对象 contactInfo 作为参数, 这个对象描述了被修改联系人的相关信息,done 执行成功的回调,fail 执行失败的回调

contactInfo

类型: object
联系人信息,参考contactInfo,id必填

done

类型: function ,可选
成功回调,没有回调参数

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 操作失败(id不存在)
99 id为空
@section('修改联系人信息示例代码')
//修改联系人信息
kk.contact.find({
  'name':'Joyce.He',
  'phone':'13499997777',
}, function( res ){
  kk.contact.update({
      id: res[0].id,     // 必填
      name: 'Joyce.He',
      phones: '13499998888'
  }, function(){
    console.log('修改成功');
  }, function(){
    console.log('修改失败');
  });
}, function(){
  console.log( '需要删除的联系人不存在' );
});
@endsection

kk.contact.find(options, done, [fail])

查找联系人
接收一个对象 options 作为参数, 这个对象描述了查找条件,done 执行成功的回调,fail 执行失败的回调

options

类型: object
查找条件

options.name

类型: string
联系人姓名,可选

options.phone

类型: string
联系人手机号码,可选

done(contacts)

类型: function
成功回调,接收数组为参数,数组元素为联系人信息对象,每个对象的形式参考contactInfo

fail

类型: function,可选
失败回调

@section('查找联系人示例代码')
//查找联系人
kk.contact.find({
    name: 'Joyce.He',
    phone: '13499997777'
}, function( contacts ){

    // 如果通讯录有重复的记录,则会返回多条
    for( var i=0; i<contacts.length; i++ ){
      console.log('联系人姓名:' + contacts[i].name + ',联系人电话:' + contacts[i].phones);
    }
}, function(code, msg){
  console.log('查找失败,code:' + code + ',msg:' + msg);
});
@endsection

kk.contact.choose([options],done, [fail])

选择联系人
接收一个可选 options 对象,done 成功回调,fail 失败回调

options

类型: object,可选
查找条件

options.mode

类型: number,可选,默认值为 1
选择类型模式,默认为1

选择类型模式 含义
1 选择人
2 选择电话号码
3 选择邮件地址

done(contacts)

类型:function
成功回调,接受contacts数组

contacts.id

类型: string
一个全局的唯一标识

contacts.name

类型: string
名字

contacts.mobile

类型: string|array
电话号码,当 mode 为2时,是字符串,其他情况下是数组,即多个电话号码

contacts.email

类型: string|array
邮箱地址,当 mode 为3时,是字符串,其他情况下是数组,即多个邮箱地址

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 用户取消了选择
-3 kk无通讯录权限
-6 参数错误
@section('选择联系人示例代码')
//查找联系人
kk.contact.choose({
    mode: 2
}, function( res ){
 /*res值示例
 [{
    'id':'899',
    'name':'移动',
    'phones':'13800138000',
    'emails':'yidong@qq.com'},
  {
    'id':'1554',
    'name':'电信',
    'phones':'10000',
    'emails':'dianxin@qq.com'
  }]
 */
}, function(code, msg){
  console.log('查找失败,code:' + code + ',msg:' + msg);
});
@endsection

不带参数mode

@section('选择联系人示例代码')
kk.contact.choose( function( contacts ) {
  /*contacts 值示例
 [{
    'id':'899',
    'name':'移动',
    'phones':'13800138000',
    'emails':'yidong@qq.com'},
  {
    'id':'1554',
    'name':'电信',
    'phones':'10000',
    'emails':'dianxin@qq.com'
  }]
 */
  });
@endsection

企业通讯录模块

门户通讯录模块 提供了访问门户(客户端)自身通讯录的能力

contactInfo

类型: object
联系人的信息

contactInfo.userID

类型: string
员工ID

contactInfo.loginName

类型: string
联系人登录名称

contactInfo.name

类型: string
联系人姓名

contactInfo.depart

类型: string
联系人直属部门名称

contactInfo.mobile

类型: string
手机号码

contactInfo.email

类型: string
邮箱地址

contactInfo.deptPath

类型: array
员工所在所有部门名称,由顶层部门到底层部门依次排列

contactInfo.jobTitle

类型: string
职位信息

contactInfo.signature

类型: string
用户个人签名

kk.econtact.choose([options], done, [fail])

企业通讯录里面选择联系人,接收一个对象 options ,这个对象描述要选择联系人的配置项, done 是成功回调函数, fail 是失败回调函数。

options

类型: object,可选
传入配置项对象

options.initList

类型: array
初始选中的联系人ID集合,为数组,可选,数组内的每一项为字符串,字符串为联系人的userID,如例: initList: ['332','178']

options.isSticky

类型: boolean
默认 false ,被选中的联系人是否被取消选中(可否编辑), true 为不可取消 false 为可以被编辑,可选 (ps:设置true时,输出的联系人并不包含initList数组里面的联系人)

options.stickyList(注意此参数目前暂时不处理)

类型: array
初始化联系人中不可被移除的联系人ID,isStickytrue 时该参数无效

options.maxCount

类型: number
默认是0,最多可选择的人数(包含initList里面的人),0 表示不限制人数

options.isSelfSticky

类型: boolean
是否默认带上自己并且不可移除

done(contactInfo)

类型: function
成功回调,返回包含被选择的联系人信息对象的数组,联系人信息结构请见 顶部contactInfo 描述

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string 错误信息

错误代码 错误信息
-1 用户取消了选择

基础用法

@section('选择企业通讯录人员示例代码')
//initList:联系人ID集合;
//isSticky:被选中的联系人是否被取消选中
var userID = kk.app.getUserInfo().userID;
kk.econtact.choose({
  'initList': [userID],
  'isSticky': false
}, function( selects ){
  /*selects 值示例
  [{
    userID:'359',//联系人ID
    name:'隔壁老王',//联系人姓名
    depart:'应用组',//联系人直属部门名称
    mobile:'13800138000',//联系人电话
    loginName:'laowang',//联系人登录名称
    email:'wyg@landray.com.cn',//联系人邮箱
    deptPath:['深圳蓝凌-47','KK产品中心-47','应用组'],//联系人所有部门名称
    jobTitle: '前端工程师', // 职位
    signature: '123456'  // 个性签名
  }]
  */
}, function( code, msg){
  console.log('选择联系人失败回调 code: ' + code +' ,msg: ' + msg );
});
@endsection

不带参数

@section('选择企业通讯录人员示例代码')
kk.econtact.choose(function( selects ){
  /*selects 值示例
  [{
    userID:'359',//联系人ID
    name:'隔壁老王',//联系人姓名
    depart:'应用组',//联系人直属部门名称
    mobile:'13800138000',//联系人电话
    loginName:'laowang',//联系人登录名称
    email:'wyg@landray.com.cn',//联系人邮箱
    deptPath:['深圳蓝凌-47','KK产品中心-47','应用组'],//联系人所有部门名称
    jobTitle: '前端工程师', // 职位
    signature: '123456'  // 个性签名
  }]
  */
}, function( code, msg){
  console.log('选择联系人失败回调 code: ' + code +' ,msg: ' + msg );
});
@endsection

kk.econtact.getUserInfo

该能力有三种调用方式:

  • kk.econtact.getUserInfo(): 查询用户的简略信息,获取当前用户信息,返回的是当前用户简略的信息
  • kk.econtact.getUserInfo(done, [fail]): 获取当前用户信息
  • kk.econtact.getUserInfo([IDs], done, [fail])获取当前用户信息,接收可选数组或字符串 IDs ,这个数组或字符串描述所需查询用户组的ID集合,done 成功回调返回的是当前用户的详细信息,结果以数组形式通过回调函数的参数进行传递, fail 失败回调。

IDs

类型: stringarray,可选
可选参数,所查询人员在企业通讯录中的ID,可以是单个人的ID,也可以是多个ID组成的数组,如例: 字符串形式 '190293'或数组形式 '[190293, 190932]'。(ps:如果所传数组里面都是不存在的ID,则返回空数组;如果数组是包含存在的ID与不存在的ID,则返回以存在的ID组成的数组。)

done(contacts)

类型: function 成功回调,返回包含被选择的联系人信息对象的数组,联系人信息结构与contactInfo一致,如果所查人员不存在,则返回结果中无其对应信息。

信息含义 信息代码
当前用户登录名 loginName
当前用户登录ID userID
当前用户姓名 userName

fail

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-9 参数错误
@section('当前用户信息(简略信息)')
//查询当前用户简略信息
var userInfo = kk.econtact.getUserInfo();
/*userInfo 值示例
  {
    userID:'139',//当前用户登录ID
    userName:'Johnson Wu',//当前用户姓名
    loginName:'Wugh'//当前用户登录名
  }
*/

@endsection
@section('当前用户信息(详细信息)')
//查询当前用户详细信息
kk.econtact.getUserInfo(function (info) {
  /*info 值示例
  [{
    userID:'139',//当前用户ID
    name:'Johnson Wu',//当前用户姓名
    depart:'研发组',//当前用户直属部门名称
    mobile:'13800138000',//当前用户电话
    loginName:'wugh'//当前用户登录名
    email:'wugh@landray.com.cn',//当前用户邮箱
    deptPath:['深圳蓝凌','KK事业部','研发组'],//当前用户所有部门名称
    jobTitle: '前端工程师', // 职位
    signature: '123456'  // 个性签名
  }]
  */
  var currentUser = info[0];
}, function (code, msg) {
  console.log('错误代码:' + code + ' ,错误信息:' + msg );
});
@endsection
@section('根据人员ID数组查询人员信息')
kk.econtact.getUserInfo([139, 359], function(info) {
 /*info 值示例
  [{
    userID:'139',//用户ID
    name:'Johnson Wu',//用户姓名
    depart:'研发组',//用户直属部门名称
    mobile:'13800138000',//用户电话
    loginName:'wugh',//用户登录名
    email:'wugh@landray.com.cn',//用户邮箱
    deptPath:['深圳蓝凌','KK事业部','研发组'],//用户所有部门名称
    jobTitle: '前端工程师', // 职位
    signature: '123456'  // 个性签名
  },{
    userID:'359',
    name:'隔壁老王',
    depart:'应用组',
    mobile:'13800138000',
    loginName:'laowang',
    email:'wyg@landray.com.cn',
    deptPath:['深圳蓝凌-47','KK产品中心-47','应用组'],
    jobTitle: '前端工程师', 
    signature: '123456'  
  }]
  */

}, function (code, msg) {
  console.log('错误代码:' + code + ' ,错误信息:' + msg );
});
@endsection

kk.econtact.getUserAvatar

该能力有三种调用方式:

  • kk.econtact.getUserAvatar() 获取当前企业用户自身头像地址 ,获取当前用户(自身)头像url,返回url字符串。
  • kk.econtact.getUserAvatar(loginName) 获取指定登陆名的用户头像,返回url字符串。
  • kk.econtact.getUserAvatar(userID, true) 获取指定登陆ID的用户头像,接收两个参数,分别为字符型的 useID 与布尔值 true

loginName

类型: string
所查询人员在企业通讯录中的登录名

userID

类型: string 所查询人员在企业通讯录中的用户ID

isById

类型: boolean
默认为 false ,即默认通过登录名查询,若为 true ,则通过用户ID进行查询

@section('获取自身头像示例代码')
var selfAvatarUrl = kk.econtact.getUserAvatar();
console.log('自身头像url: ' + selfAvatarUrl);
@endsection
@section('通过登录名获取头像示例代码')
//根据企业用户登录名获取头像
var avatarUrl = kk.econtact.getUserAvatar('user1');
console.log('头像url: ' + avatarUrl);
@endsection
@section('通过用户ID获取头像示例代码')
//根据企业用户ID获取头像
var avatarUrl = kk.econtact.getUserAvatar(190293, true);
console.log('头像url: ' + avatarUrl);
@endsection

kk.econtact.startChat(options, [done], [fail])

发起与用户的会话,接收一个对象 options,这个对象描述的是发起会话的配置参数, done 是成功回调函数, fail 是失败回调函数。

options

类型: object
配置参数

options.userID

类型:string
你想发起会话的对象的用户ID(userID),选填

options.loginName

类型:string
你想发起会话的对象的登录名(loginName),选填

注意

  • userIDloginName都是选填,但是二者必须选一个去传值;
  • userIDloginName都传时,客户端会优先使用 userID去发起会话;

options.words

类型:string
发送的内容,发起会话成功后内容显示在输入框(还没发送),选填

done()

类型: function,可选
成功回调, 此回调函数在成功发起会话后立即执行(并非是从会话页面返回后再执行)

fail(code,msg)

类型: function,可选
失败回调,此回调函数在发起会话失败后立即执行;

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
991 参数不可用
-2 找不到对应的员工
@section('根据用户的userID去发起会话')
// 根据用户的userID去发起会话
kk.econtact.choose(function(selects) {
    var userID = selects[0].userID;
    kk.econtact.startChat({
      userID: userID,
    }, function () {
      console.log('发起会话成功');
    }, function (code, msg) {
      console('发起会话失败:code:' + code + '错误信息:' + msg);
    });
}, function( code, msg){
    console.log('选择联系人失败回调 code: ' + code +' ,msg: ' + msg);
});
@endsection
@section('根据用户的userID去发起会话, 有内容')
//根据用户的userID去发起会话,有内容,内容为words里面的内容
kk.econtact.choose(function(selects) {
    var userID = selects[0].userID;
    kk.econtact.startChat({
      userID: userID,
      words: '请查看流程: xxxxx, 链接 http://www.xxx.xxx/xxxx'
    }, function () {
      console.log('发起会话成功');
    }, function (code, msg) {
      console('发起会话失败:code:' + code + '错误信息:' + msg);
    });
}, function( code, msg){
    console.log('选择联系人失败回调 code: ' + code +' ,msg: ' + msg);
});
@endsection

kk.econtact.showECard(options, [done], [fail])

显示联系人资料页面,接收一个对象 options,这个对象描述的是显示资料页面的配置参数, done 是成功回调函数, fail 是失败回调函数。

options

类型: object
配置参数

options.uesrID

类型:string
显示联系人资料页面的联系人的用户ID(userID),选填

options.loginName

类型:string
显示联系人资料页面的联系人的登录名(loginName),选填

注意

  • userIDloginName都是选填,但是二者必须选一个去传值;
  • userIDloginName都传时,客户端会优先使用 userID去显示联系人资料页面;

done()

类型: function,可选
成功回调, 此回调函数在成功显示资料页面后立即执行(并非是从资料页面返回后再执行)

fail(code,msg)

类型: function,可选
失败回调,此回调函数在显示资料页面失败后立即执行;

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
991 参数不可用
-2 找不到对应的员工
@section('根据用户的userID去显示资料页面')
// 根据用户的userID去显示资料页面
kk.econtact.choose(function(selects) {
    var userID = selects[0].userID;
    kk.econtact.showECard({
      userID: userID,
    }, function () {
      console.log('显示资料页面成功');
    }, function (code, msg) {
      console('显示资料页面失败:code:' + code + '错误信息:' + msg);
    });
}, function( code, msg){
    console.log('选择联系人失败回调 code: ' + code +' ,msg: ' + msg);
});
@endsection
@section('根据用户的loginName去显示资料页面')
//根据用户的loginName去显示资料页面
kk.econtact.choose(function(selects) {
    var loginName = selects[0].loginName;
    kk.econtact.showECard({
      loginName: loginName
    }, function () {
      console.log('显示资料页面成功');
    }, function (code, msg) {
      console('显示资料页面失败:code:' + code + '错误信息:' + msg);
    });
}, function( code, msg){
    console.log('选择联系人失败回调 code: ' + code +' ,msg: ' + msg);
});
@endsection

电话短信模块

电话短信模块,提供了拨打电话、发送短信能力

kk.phone.call(options, [done], [fail])

拨打电话

options

类型:object|number
拨打电话的信息,支持 对象形式或者数字形式

options为数字时

类型:number
电话号码

options为对象时

options.number

类型:number
电话号码

options.needCallSessionInfo

类型:boolean, 默认值 false
是否需要通话信息,true 表示需要通话信息,

done(args)

类型:function,可选
成功回调,接收包含通话信息的对象args作为参数。

args.callState

类型:string
通话状态:

  • 1: 未接通
  • 2: 通话完成

注意:只有在 args.callState值是 2时才会返回以下字段

args.startTime

类型:date
通话开始的时间

args.endTime

类型:date
通话结束的时间

args.sessionTime

类型:string
通话时长,单位是秒

args.startTimeString

类型:string
通话开始时间字符串,以yyyymmddhhmmss格式显示

args.endTimeString

类型:string
通话结束时间字符串,以yyyymmddhhmmss格式显示

fail

类型: function
失败回调, 仅当需要通话信息(即options.needCallSessionInfotrue),用户使用Android 系统,且用户未允许KK读取通话记录的权限时才会调用

@section('传数字')
//拨出号码
kk.phone.call(10086);
@endsection

@section('传对象')
//拨出号码并且需要通话信息
kk.phone.call({
  number: 10086,
  needCallSessionInfo: true
}, function (res) {
  /*res 值示例
  {
    "callState":"2",  // 通话状态:通话完成
    // callState值为2时才会有以下字段
    "startTime":Thu Jul 06 2017 16:17:53 GMT+0800 (CST),  
    sessionTime:"8", // 通话时长
    startTimeString:"20170706161753",
    endTime:Thu Jul 06 2017 16:18:01 GMT+0800 (CST),
    endTimeString: "20170706161801"
  } 
  */
  console.log('通话状态:' + res.callState);
});
@endsection

kk.phone.sms(phoneNumber, [content])

发送短信

phoneNumber

类型: string 电话号码

content

类型: string,可选 短信内容

@section('发送短信示例代码')
//发送短信
kk.phone.sms('10086', '打造大连接,蓝凌全新企业移动互联解决方案');
@endsection

设备模块

设备模块可以设置设备屏幕显示方向及获取网络类型

kk.device.setOrientation(orientation)

设置设备屏幕的显示方向,接收一个参数 orientation,用于描述屏幕方向的参数

orientation

类型: string
可选值:

  • portrait(竖屏)
  • landscape(横屏)
  • auto(自动旋转)
@section('设置屏幕方向为竖屏')
// 将屏幕设置为竖屏
kk.device.setOrientation('portrait');
@endsection
@section('设置屏幕方向为横屏')
// 将屏幕设置为横屏
kk.device.setOrientation( 'landscape');
@endsection
@section('设置屏幕方向为自动旋转')
// 将屏幕设置为自动旋转
kk.device.setOrientation('auto');
@endsection

kk.device.getOrientation(done, [fail])

获取设备屏幕显示方向

done(args)

类型: function
成功回调,接收一个字符串作为参数

args

类型: string
可能值:

  • portrait(竖屏)
  • landscape(横屏)
  • auto(自动旋转)

fail

类型: function,可选
失败回调

@section('获取屏幕显示方向')
// 获取屏幕显示方向
kk.device.getOrientation(function(res){
   /*res 值示例
    res: 'portrait'
  */
  console.log(res); 
})
@endsection

kk.device.getNetType(done, [fail])

获取设备当前的网络类型,返回成功回调函数 done 或者失败回调函数 fail

done(args)

类型: function
成功回调,接收包含网络类型的对象作为参数

args.netType

类型: string
可能值2G/3G/4G/WIFI,空字符串代表无网络,iOS下2G/3G均返回3G

fail

类型: function,可选
失败回调

@section('获取网络类型示例代码')
// 获取网络类型 
kk.device.getNetType( function( res ){
    /*res 值示例
  {
     netType:'WIFI'
  }
  */
  var netType = res.netType;
  switch( netType ){
    case '':
      // 无网络,使用本地数据
      break;
    case '2G':
      // 使用远程文本内容
      break;
    case '3G':
      // 使用远程的图片
      break;
    case '4G':
      // 使用远程的图片
      break;
    case 'WIFI':
      // 使用远程的视频
      break;
  }
});
@endsection

kk.device.setClipboard(text)

设置剪贴板内容,接收一个字符串 text,描述要设置的内容。

text

类型: string
要拷贝的内容

@section('设置剪贴板内容示例代码')
// 设置剪贴板内容
kk.device.setClipboard( 'Welcome to kk' );
@endsection

媒体模块

媒体模块,封装了拍照、录音、录制视频、选择相册图片、存储图片、播放音视频等能力

kk.media.getPicture([options,] done, [fail])

拍照(单张),获取单张照片或者从相册中选取一张照片。

options

类型: object,可选
配置参数

options.count

类型: number,可选,默认值为 1
获取的图片张数,默认为1张。

options.sourceType

类型: string,可选,默认值为 camera(使用摄像头拍照)
数据来源即从何处获取图片,可选值有:

  • camera 摄像头拍照, 此为默认值
  • album 从相册中选取

options.destinationType

类型: string,可选,默认值为 file(存为文件)
图片的数据存储类型。可选值有:

  • file 存储为文件,当获取多张图片时,此为默认值
  • data 存为 base64 字符串,仅获取单张图片时,此类型合法,多张时能力将提示错误。

options.targetWidth

类型: number,可选,默认值为 100
期望的图片宽度,缺省为100,单位px

options.targetHeight

类型: number,可选,默认值为 100
期望的图片宽度,缺省为100,单位px

options.encodingType

类型: string,可选,默认值为 png
期望得到的图片的格式(jpeg/ png),缺省为png

options.quality

类型: number,可选,默认值为 50
图片压缩比 0-100,缺省为50, encodingType 为png时,该参数无效。图片压缩比越大(数值越大),图片的质量越好,文件所占的存储空间越大。

options.savePath

类型: string 或者 array
文件的保存至手机的路径(string类型),或图片保存路径组成的数组(array类型)。获取单张时可以是string,多张时则必须是 array。 图片保存的路径格式可参考路径说明。 仅 destinationTypefile 时该参数有意义。若没有传入,则系统自动生成一个路径;若 options.savePath 指定的文件存储路径比 options.count 少,则缺少的部分系统会自动产生其路径。

options.exifFlag

类型: boolean,可选,默认是 false
是否在照片信息中保存GPS位置信息

done(args)

类型: function
成功回调。当未设置 options.count(即获取单张图片) 时, args 为一个图片信息对象,当设置之后(不论设置为 1 还是更多), args 为包含 options.count 个数的图片信息对象的数组。

图片信息对象格式

imageInfo.imageData

类型: string
图片的base64编码,可以直接设置为 <img> 标签的 src 来使用 , destinationType = data时返回

imageInfo.imageFileOSPath

类型: string
图片在操作系统上的实际路径 ,destinationType = file 时返回, 可直接作为图片的src来显示

imageInfo.imageURI

类型: string
保存文件的协议路径(若没有传入,则系统自动生成一个路径) , destinationType = file 时返回

imageInfo.imageTime

类型: date
图片创建时间对象 , 当destinationType = file时 有该值

imageInfo.imageTimeString

类型: string
图片创建时间字符串,以yyyymmddhhmmss格式显示 , 当options.destinationTypefile 时 有该值

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-90 参数错误
-1 获取错误
@section('拍照(数据类型:file)')
//拍照(数据类型:file)
kk.media.getPicture({
  sourceType: 'camera',
  destinationType: 'file',
  encodingType: 'png',
  savePath: 'sdcard://media/photo/single.png'
}, function(res){
  /* 
   * 因为未设置拍照张数(count) res 为一个图片信息对象, res 值示例如下
  {
    imageURI:'sdcard://media/photos/single.png',
    imageFileOSPath:'kkapp://fi.o-1091-o.kk/storage/sdcard1/media/photo/single.png',
    imageTime:'2017-02-28T05:28:08.000Z',
    imgaeTimeString:'20170228132808'
  }
  */
  // res.imageFileOSPath, 可以直接设置为<img>标签的src来使用
  // res.imageURI,可以作为kk.media.save2album()的filepath,将相片保存到相册
}, function(code, msg){
  console.log('错误信息:' + msg + ', 错误代码:' + code);
});
@endsection

@section('拍照(数据类型:data)')
// 从相册中选取(数据类型:data,仅获取单张图片时数据类型才可以是 data)
kk.media.getPicture({
  sourceType: 'camera',
  destinationType: 'data'
}, function(res){
  /*res 值示例
  {"imageData":"data:image/png;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBA…oAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKAP/Z"} */
  //res.imageData, 可以直接设置为<img>标签的src来使用
}, function(code, msg){
  console.log('错误信息:' + msg + ', 错误代码:' + code);
});
@endsection
@section('从相册中选取多张图片(数据类型:file)')
//从相册中选取(数据类型:file)
kk.media.getPicture({
  sourceType: 'album',
  destinationType: 'file',
  encodingType: 'png',
  count: 2
}, function(res){
  /*设置了count值,res 是一个数组,值示例
  [{
    imageFileOSPath: "kkapp://fil.o-1213-o.kk/storage/sdcard1/easymi/1498118521731.png",
    imageTime: Thu Jun 22 2017 16:02:01 GMT+0800 (CST),
    imageTimeString: "20170622160201",
    imageURI: "sdcard://easymi/1498118521731.png"
  }, {
    imageFileOSPath: "kkapp://fil.o-1213-o.kk/storage/sdcard1/easymi/1498118521882.png",
    imageTime: Thu Jun 22 2017 16:02:01 GMT+0800 (CST),
    imageTimeString: "20170622160201",
    imageURI: "sdcard://easymi/1498118521882.png"
  }]
  */
  //res[0].imageFileOSPath,res[1].imageFileOSPath 可以直接设置为<img>标签的src来使用
  //res[0].imageURI,res[1].imageURI可以作为kk.media.save2album()的filepath,将相片保存到相册
}, function(code, msg){
  console.log('错误信息:' + msg + ', 错误代码:' + code);
});
@endsection

@section('从相册中选取(数据类型:data)')
// 从相册中选取(数据类型:data,仅获取单张图片时数据类型才可以是 data)
kk.media.getPicture({
  sourceType: 'album',
  destinationType: 'data'
}, function(res){
  /*res 值示例
  {"imageData":"data:image/png;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBA…oAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKAP/Z"} */
  //res.imageData, 可以直接设置为<img>标签的src来使用
}, function(code, msg){
  console.log('错误信息:' + msg + ', 错误代码:' + code);
});
@endsection

kk.media.getSignImage(options, done, [fail])

获取签名的图片

options

类型: object
配置参数

options.width

类型: number
输出的图片宽度,单位px

options.height

类型: number
输出的图片高度(和width配合,同时使用),单位px

options.penSize

类型: number(2)
画笔的粗细:1.细,2.一般,3.粗,缺省为2

options.penColor

类型: number(1)
画笔的颜色:1.黑,2.蓝,3.红,缺省为1

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.resultPath

类型: string
保存签名图片的路径

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-90 参数错误
-3 处理图片错误
-1 用户取消
@section('获取签名图片示例代码')
kk.media.getSignImage({
  width: 100,
  height: 100,
  penSize: 3,
  penColor: 2
}, function(res){
  /*res值示例
    {
      resultPath:'kkapp://fil.o-1091-o.kk/storage/sdcard1/Pictures/Drawings/1488260710738.png'
    }
  */
  console.log('签名图片的路径:' + res.resultPath);
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.media.save2album(options, [done], [fail])

保存图片到相册

options

类型: object
配置选项

options.filepath

类型: string
要保存的照片路径,可以是在线图片

done

类型: function,可选
成功回调

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 文件不存在
9 保存到相册失败
-90 参数错误
@section('保存本地图片到相册')
//保存本地图片到相册 
kk.media.save2album({
  // 填写正确的本地文件路径
  uri: 'sdcard://media/photo/multi/101.jpeg'
}, function(){
  console.log('照片保存成功');
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection
@section('保存在线图片到相册')
//保存在线图片到相册 
kk.media.save2album({
  // 填写带协议的完整的路径
  uri: 'http://www.baidu.com/icon.jpg'
}, function(){
  console.log('照片保存成功');
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.media.previewImage(options, [fail])

预览图片,使用原生UI来浏览图片(可以是多张图片), 并支持图片的缩放操作

options

类型: object
配置参数

options.paths

类型: array
所要预览图片的地址列表,暂时仅支持传入本地图片地址, 即文件路径列出的几种地址

options.current

类型: int
当前图片的索引(在列表中的序号), 索引从0开始计数

options.operations

类型: boolean
是否提供图片操作菜单(转发到微信好友/保存到相册)

true:提供,false:不提供。默认为 false

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 路径参数为空
999 预览失败(地址没有按顺序填写,中间存在空值)
@section('预览图片示例代码')
// 预览图片
kk.media.previewImage({
  paths: [
    'sdcard://1.jpg',
    'sdcard://2.jpg',
    'sdcard://3.jpg',
  ]
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.media.captureVideo([options], done, [fail])

录制视频,录制的格式取决于操作系统,下面有说明

视频录制格式:

设备 格式
Android下 录制的格式为3gp
iOS下 录制的格式为mov

options

类型: object,可选
配置参数

options.quality

类型: string,可选值:LOW,MEDIUM,HIGH ,默认值是 LOW 质量参数

options.savePath

类型: string
要保存的路径 (如果不指定,将使用sdcard://协议保存一个随机文件名)

options.duration

类型: number
录像时长(单位:秒;如果不指定,则默认长度不做限制)

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.name

类型:string
不含路径信息的文件名

args.fullPath

类型: string
包含文件名的文件全路径

args.type

类型: string
MIME类型

args.lastModifiedDate

类型: string
文件最后修改的日期和时间,如20150629154714,表示最后修改时间是"2015年06月29日15时47分14秒"

args.size

类型: number
文件大小(单位为字节)

args.endingType

类型: number
录制结束方式,0:主动结束,1:来电或其他因素打断

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 用户取消
-2 创建录制文件失败
1 请求的视频规格不支持
@section('录制视频示例代码')
//录制视频
kk.media.captureVideo({
  quality: 'MEDIUM',
  savePath: 'sdcard://media/video/test.mov',
  duration: 20
}, function(res){
  /*
    res值示例:
    {
      endingType:0,//录制结束方式
      retCode:0,
      name:'test.mov',//文件名
      fullPath:'sdcard://media/vedio/test.mov',//文件全路径
      type:'3gp',//MIME类型
      lastModifiedData:'2017-02-28 13:51:21',//最后修改的时间
      size:218488//文件大小
    }
  */
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.media.captureAudio(done, [fail])

带native UI的录音能力

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.name

类型: string
文件名

args.fullPath

类型: string
文件在系统上的绝对路径

args.type

类型: string
文件类型

args.size

类型: number
文件大小(单位为字节)

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
±3 录音被取消了
-9 录音错误
@section('录音示例代码')
//带native UI的录音
kk.media.captureAudio(function(res){
  /*res 值示例
  { 
    name:'ekp_1488261335494.amr',//文件名
    fullPath:'/data/data/com.landray.kkplus/files/ekp_1488261335494.amr',//文件全路径
    type:'audio/amr',//文件类型
    size:3654//文件大小
  }
  */
}, function(code, msg){
  if(code == -3){
    console.log('录音被取消了');
  }else if(code == -9){
    console.log('录音错误');
  }else{
    console.log('录音失败');
  }
});
@endsection

kk.media.playAudio(filePath, [fail])

带native UI的音频播放能力

filePath

类型: string
音频文件路径

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-3 播放被取消了
-9 播放错误
@section('音频播放示例代码')
//带native UI的音频播放
kk.media.playAudio('sdcard://media/audio/test.wav', function(code, msg){
  console.log('音频播放失败,错误代码:' + code + ' ,错误信息:' + msg );
});
@endsection

加密/解密模块

加密模块提供文件、字符串的加密和解密能力

kk.crypto.encrypt(options, done, [fail])

加密字符串,接收一个对象 options ,这个对象描述了要加密的字符串的配置参数, done 成功回调,fail 失败回调。

options

类型: object
配置参数

options.text

类型: string
要加密的字符串

options.key

类型: string
密钥

done(arg)

类型: function
成功回调,返回一个参数 arg ,这个参数描述了加密后的字符串。

arg

类型: string
加密后的字符串

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 加密失败
@section('加密字符串示例代码')
//加密字符串
kk.crypto.encrypt({
  text: '需要加密的字符串',
  key: 'mykey'
}, function( res ){
 /* res 值示例 
  {
    retCode:'0',
    text:'54vsRgkdgRk0bvBcPZYdx3jwYTevd8591lXSBBctp7k='
  }
  */
  console.log('加密后的字符串:' + res.text );
  localStorage.encryptText = res.text;
},function( code, msg ){
  console.log('错误代码:' + code + ' ,错误信息:' + msg );
});
@endsection

kk.crypto.decrypt(options, done, [fail])

解密字符串,接收一个对象 options ,这个对象描述要解密字符串的配置参数, done 成功回调,fail 失败回调。

options

类型:object
传入的配置参数对象

options.text

类型: string
被加密的字符串

options.key

类型: string
密钥

done(args)

类型: function
成功回调,返回一个对象 args ,描述解密后的字符串。

args.text

类型: string
解密后的字符串

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 解密失败
@section('解密字符串示例代码')
//解密字符串
var encryptText = localStorage.encryptText;
// encryptText 是一段加密后的字符串,类似 '7kxl8E55rJFm642Oelilew==';
kk.crypto.decrypt({
  text: encryptText,
  key: 'mykey'
}, function( res ){
 /* res 值示例
  {
    retCode:'0',
    text:'需求加密的字符串'
  }
  */
  console.log('解密后的字符串:' + res.text );
}, function( code, msg ){
  console.log('错误代码:' + code + ' ,错误信息:' + msg );
});
@endsection

kk.crypto.obscureFile(options, [done], [fail])

加密文件,接收一个对象 options ,这个对象描述要加密文件的配置选项, done 成功回调,fail 失败回调。

options

类型: string
配置选项

options.obscure

类型: string
混淆因子(密钥)

options.sourceFile

类型: string
源文件路径

options.dealSourceFile

类型: boolean
是否直接处理源文件,为 true 时,忽略 outputFile 属性

options.outputFile

类型: string
文件输出路径,dealSourceFiletrue 时,此属性无效

done

类型: function,可选
成功回调,无回调参数

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 源文件不存在或源文件数据为空
@section('加密文件:保持加密文件路径不变')
// 混淆文件:保持加密文件路径不变
kk.crypto.obscureFile( {
  obscure: 'mykey2',
  sourceFile: 'sdcard://test/abc.mov',
  dealSourceFile: true
}, function( ){
  console.log('文件加密成功');
}, function( code, msg ){
  console.log('文件加密失败,错误代码:' + code + ',错误信息:' + msg);
});
@endsection
@section('加密文件:文件加密后复制到其他路径')
// 混淆文件:文件加密后复制到其他路径
kk.crypto.obscureFile( {
  obscure: 'mykey2',
  sourceFile: 'sdcard://test/abc.mov',
  outputFile: 'sdcard://output/123.mov'
}, function( ){
  console.log('文件加密成功');
}, function( code, msg ){
  console.log('文件加密失败,错误代码:' + code + ',错误信息:' + msg);
});
@endsection

kk.crypto.restoreFile(options, [done], [fail])

解密文件,接收一个对象 options ,这个对象描述要解密文件的配置选项, done 成功回调,fail 失败回调。

options

类型: object
传入配置选项对象

options.obscure

类型: string
混淆因子

options.sourceFile

类型: string
源文件路径

options.dealSourceFile

类型: boolean
是否直接处理源文件,为 true 时,忽略 outputFile 属性

options.outputFile

类型: string
文件输出路径,dealSourceFiletrue 时,此属性无效

done

类型: function,可选
成功回调,不接收参数

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 源文件不存在或源文件数据为空
@section('解密文件:删除加密的源文件')
//解密文件
kk.crypto.restoreFile( {
  obscure: 'mykey2',
  sourceFile: 'sdcard://output/123.mov',
  dealSourceFile: true
}, function(){
  console.log('文件解密成功,' );
}, function( code, msg ){
  console.log('文件解密失败,错误代码:' + code + ',错误信息:' + msg);
});
@endsection
@section('解密文件:保留加密的源文件')
// 保留加密的源文件,解密密后生成新的文件
kk.crypto.restoreFile( {
  obscure: 'mykey2',
  sourceFile: 'sdcard://output/123.mov'
  outputFile: 'sdcard://test/tmp.mov',
}, function( ){
  console.log('文件解密成功');
}, function( code, msg ){
  console.log('文件解密失败,错误代码:' + code + ',错误信息:' + msg);
});
@endsection

代理模块

代理请求模块,封装了与服务器进行数据交互的能力。

Proxy.request调用方式类似于$.ajax,可以与服务器进行文本数据交互。

Proxy.Download和Proxy.Upload可以和服务器之间进行文件的下载和上传,支持断点续传。这两个能力被封装成了类,需要 new 创建实例来使用。

注意 使用 Download和Upload能力前,必须先在KK管理台应用管理中对应应用的设置中设置 资源上传下载地址,使用能力时的下载地址/上传地址(只能是相对地址) 均相对于该地址。 (附资源上传下载地址所在的kk管理台位置) url-proxy

kk.proxy.request(options)

代理请求,支持类似于 jQuery.ajax 的 promise 写法。调用该能力后返回一个 promise 对象。

options

类型: object
请求参数设置。当有多个请求的请求参数有共同的设置时,可以尝试使用 kk.proxy.requestSetup 来设置默认值。

options.url

类型: string
请求的URL。实际URL是管理台配置的地址和相对地址拼接起来的地址

options.data

类型:object/string
请求的参数,以JSON形式的Object或者字符串

options.contentType

类型: string, 默认值 form
发送参数时的编码格式,可自定义。能力预定义了两个简写格式:form/ json,含义如下:

  • form: 以普通表单形式发送请求体,默认值, 为格式 application/x-www-form-urlencoded; charset=UTF-8 的缩写
  • json: 以JSON字符串形式发送请求体, 为格式 application/json; charset=UTF-8 的缩写

options.dataType

类型: string,可选值有text/json
返回数据格式,为json时,返回的数据就是一个json对象

options.beforeSend(options)

类型: function, 可选
在发送请求前执行该函数,在此函数中可对请求参数进行处理

options.headers

类型: object
额外的http头

options.success(args)

类型: function
成功回调,接收一个对象 args 作为参数。 亦可以使用 promise 写法来传递成功回调。

args:

类型: string/object
返回数据类型 form 时对应类型是 string ,返回数据类型 json 时对应的类型是 object

options.error(code,msg)

类型: function
失败回调, 亦可以使用 promise 写法来传递失败回调。

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
102 代理请求失败,常见原因:1. KK服务器无法访问到接口服务器 2. 接口地址错误 3. 接口服务器无法正常访问(比如服务器响应500、403等错误)

返回值: promise 对象

返回的 promise 对象具有以下方法 var promise = kk.proxy.request(...);

promise.then(done, [fail])

设置请求执行完成后的成功回调(done) 及 失败回调(fail), 接收的相关参数与 options.success 及 options.error 一致。

promise.done(done)

设置请求执行完成后的成功回调(done), 接收的相关参数与 options.success 一致。

promise.fail(fail)

设置请求执行完成后的失败回调(fail), 接收的相关参数与 options.error 一致。

promise.always(finally)

设置回调函数,当请求执行完后即执行, 不论成功或失败,均会执行。

基础用法

@section('代理请求示例代码')
//代理请求
kk.proxy.request({
    url: '/remote-api-server-url',//请求的URL
    data: {//请求的参数,JSON Object
        "username": "landray",
        "password": "connect"
    },
    dataType: 'json',//返回数据格式
    success: function( res ){//成功回调
        console.log(JSON.stringify(res));
    },
    error: function( code, msg ){//失败回调
        console.log('代理请求失败,错误代码:' + code + ' ,错误信息: ' + msg );
    }
});
@endsection

使用 promise 方式调用

@section('使用promise方式调用')
kk.proxy.request({
    url: '/remote-api-server-url'
    contentType: 'json',//参数的编码格式
    dataType: 'json',//返回数据格式
    headers: {//额外的http头
        'Accept-Language': 'zh',
        'Date': 'HTTP-date'
    },
    data: {                     //请求的参数,JSON Object
        "username": "landray",
        "password": "connect"
    }
}).done(function(res){
    // 处理返回结果
}).fail(function(code, msg)) {
    console.log('错误信息:' + msg + ', 错误代码:' + code);
}).always(function(){
    console.log('请求执行结束')
});
@endsection

使用 kk.proxy.requestSetup 设置默认请求参数

@section('代理请求:预先设定默认参数')
//如果多个请求参数相同,可以设置默认参数以简化请求
var req = kk.proxy.requestSetup({
    contentType: 'json',//参数的编码格式
    dataType: 'json',//返回数据格式
    headers: {//额外的http头
        'Accept-Language': 'zh',
        'Date': 'HTTP-date'
    },
    beforeSend: function( options ) {
        // 可在此处修改请求相关参数,比如修改请求地址
        // options.url = '/api' + options.url

        console.log('接口URL: ' + options.url)
    },
    error: function(code, msg){//失败回调
        console.log('错误信息:' + msg + ', 错误代码:' + code);
    }
});
//简化后的请求
req.request({
    url: '/remote-api-server-url';         //请求的URL
    data: {                     //请求的参数,JSON Object
        "username": "landray",
        "password": "connect"
    },
    success: function( res ){
        console.log(JSON.stringify(res));
    }
});
@endsection

kk.proxy.requestSetup(options)

设置 kk.proxy.request 请求的默认参数,返回设置后参数集合对象。当应用中所有的请求都有一样的请求设置时,即可用该函数设置默认参数,设置后会影响所有 kk.proxy.request 发起的请求。调用 kk.proxy.request 时若不设置相关值则使用默认参数,若设置了则使用设置的值。

options

类型: object
配置参数, 支持的配置内容与 kk.proxy.request 的 options 一样

kk.proxy.Upload(options, done, fail)

文件上传能力的构造函数,使用时需使用 new 创建实例后使用。

options

类型: object
配置参数

options.url

类型: string
文件上传至服务器的地址

options.path

类型: string
文件在本地地址

options.isContinuous

类型: boolean
是否断点续传,true表示断点续传,默认false

done(args)

类型: function
成功回调,接收一个对象作为参数args,上传过程中会不停调用该回调, 直至上传完成

args.progress

类型: number
文件已上传进度,0~100,当上传至100时表示上传完成

args.path

类型: string
文件在本地的地址,上传完成时才会有该属性

fail

类型: function
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 未连接到服务器
-2 文件本地地址为空
-3 和服务器交互发生异常
404 上传的文件不存在
其他数字 透传服务端错误码
@section('文件上传构造函数示例代码')
// 创建一个代理实例
var proxy = new kk.proxy.Upload({
    url: '/upload/test.txt',        //文件上传至服务器的地址
    path: 'sdcard://upload.txt',    //文件在本地地址
    isContinuous: false             //是否断点续传,默认不支持断点续传
}, function(res){
    if(res.progress != 100){
        console.log('上传进度:' + res.progress);    
    }else{
        console.log('上传完成,文件地址:' + res.path);
    }
}, function(code, msg){
    console.log('错误信息:' + msg + ',错误代码:' + code);
});
// 开始上传
proxy.start();
// 暂停上传,注意,暂停是异步的,会有一点延时
proxy.pause();
// 恢复上传
proxy.resume();
// 停止上传,也是异步的
proxy.stop();
@endsection

kk.proxy.Download(options, done, fail)

文件下载能力的构造函数,使用时需使用 new 创建实例后使用。

options

类型: object
配置参数

options.url

类型: string
文件在服务器的地址

options.path

类型: string
文件保存到本地的地址

options.isContinuous

类型: boolean,默认false
是否断点续传,true表示断点续传

done(args)

类型: function
成功回调,接收一个对象 args 作为参数,下载过程中会不停调用该回调, 直至下载完成

args.progress

类型: number
文件已下载进度,0-100,当下载至100时表示下载完成

args.path

类型: string
文件在本地的地址,下载完成时才会有该属性

fail(code, msg)

类型: function
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 未连接到服务器
-2 文件本地地址为空
-3 和服务器交互发生异常
210 下载内容变了
其他数字 透传服务端错误码
@section('文件下载构造函数示例代码')
// 创建一个代理实例
var proxy = new kk.proxy.Download({
    url: '/download/test.txt',//文件在服务器的地址
    path: 'sdcard://download.txt',//文件在本地地址
    isContinuous: false//是否断点续传,默认false,不支持断点续传
}, function(res){
    /*
    res 值示例
   { 
        retCode: 0,
        progress: 100,
        path: "sdcard://easymi/download.txt"
    }

    */
    if(res.progress != 100){
        console.log('下载进度:' + res.progress);    
    }else{
        console.log('下载完成,文件地址:' + res.path);
    }
}, function(code, msg){
    console.log('错误信息:' + msg + ',错误代码:' + code);
});
// 开始下载
proxy.start();
// 暂停下载,注意,暂停是异步的,会有一点延时
proxy.pause();
// 恢复下载
proxy.resume();
// 停止下载,也是异步的
proxy.stop();
@endsection

文件压缩解压缩模块

文件压缩解压缩模块,提供了文件压缩和解压缩能力

kk.zip.zip(options, [done], [fail])

压缩文件(解压压缩的文件请调用能力的解压缩模块去解压)

options

类型: object
配置选项

options.folderPath

类型: string
要压缩的文件(夹)路径

options.filePaths

类型: array
要被压缩的多个文件(夹)的路径,每一项为字符串,中间用逗号分隔。如果folderPath参数提供了,本参数会被忽略。

options.zipFilePath

类型: string
压缩生成的zip文件路径

done(args)

类型: function,可选
成功回调,返回一个对象 args 作为参数

args.zipFilePath

类型:string
压缩后的zip文件路径

args.FolderPath

类型:string
源文件(夹)的路径,Android无此属性

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 FolderPath对于native为空或者不存在
8 参数非法
9 压缩失败
@section('压缩文件示例代码')
kk.zip.zip({
  folderPath: 'sdcard://test/zipFolder',
  zipFilePath: 'sdcard://test/zipFolder.zip'
}, function(res){
  console.log('压缩后的zip文件路径:' + res.zipFilePath);
  console.log('需要压缩的文件夹:' + res.FolderPath);
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.zip.unzip(options, [done], [fail])

解压文件

options

类型: object
配置选项

options.zipFilePath

类型: string
需要解压文件(夹)的路径

options.outPath

类型: string
解压后的输出目录

done(args)

类型: function,可选
成功回调,返回一个对象 args 作为参数

args.zipFilePath

类型: string
源压缩文件的路径,Android无此属性

args.outPath

类型: string
解压后的输出目录

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 zipFilePath对于native为空或者不存在
9 解压缩失败
@section('解压文件示例代码')
kk.zip.unzip({
    zipFilePath: 'sdcard://test/zipFolder.zip', 
    outPath: 'sdcard://test/unzipFolder'
}, function(res){
    console.log('需要解压文件的路径:' + res.zipFilePath);
    console.log('解压后的输出目录:' + res.outPath);
}, function(code, msg){
    console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

文件操作模块

文件操作模块,封装了获取文件信息、查看文件、删除文件等功能

kk.file.getOSPath(filepath, done, [fail])

获取文件在操作系统上的路径,接收一个字符串 filepath , done 表示成功回调, fail 表示失败回调。

filepath

类型: string
文件路径

done(args)

类型: function
成功回调,返回一个 args 对象作为参数

args.OSPath

类型: string
文件在系统上的路径

fail

类型: function
失败回调

@section('获取文件路径示例代码')
//获取文件在操作系统中的实际路径
kk.file.getOSPath('sdcard://kktest/fileTest.txt', function(res){
  /*
  res值示例
  {OSPath:'kkapp://fil.o-1091-o.kk/storage/sdcard1/kktest/fileTest.txt'}
  */
  console.log('文件在系统上的路径: ' + res.OSPath);
});
@endsection

kk.file.getFileInfo(filepath, done, [fail])

获取文件的基础信息,接收一个描述文件路径的字符串 filepathdone 表示成功回调, fail 表示失败回调。

filepath

类型: string
文件路径

done(args)

类型: function
成功回调,返回一个对象 agrs 作为参数

agrs.name

类型: string
文件名称

agrs.size

类型: string
文件大小,单位byte

agrs.lastModifyTime

类型: string
文件最后修改时间,如20150629154714,表示最后修改时间是"2015年06月29日15时47分14秒

agrs.path

类型: string
文件的相对存储路径

agrs.isDir

类型: boolean
路径是否指向的是一个文件夹

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 文件不存在
@section('获取文件信息示例代码')
//获取文件信息
kk.file.getFileInfo('sdcard://kktest/fileTest.txt', function (info) {
  /*info 值示例
  {
    name:'1.png',//文件名称
    size: '809',//文件大小
    lastModifyTime:'20170227160048',//文件最后修改时间
    path:'/var/mobile/Containers/Data/Application/0D96B6DE-AB92-4D50-A522-26D4E5DDF016/Documents/easymi/1.png',//文件相对存储路径     (ios)
    isDir:false//是否是文件夹
  }
    */

}, function (code, msg) {
  console.log('错误信息: ' + msg + ',错误代码:' + code);
});
@endsection

kk.file.exists(filepath, done, [fail])

判断文件是否存在,接收一个描述文件路径的字符串 filepathdone 表示成功回调, fail 表示失败回调。

filepath

类型: string
文件路径

done(args)

类型: function
成功回调,返回一个对象args作为参数

args.exists

类型: boolean
true 表示文件存在,false 表示文件不存在

fail

类型: function,可选
失败回调

@section('判断文件是否存在示例代码')
//判断文件是否存在
kk.file.exists('sdcard://kktest/fileTest.txt', function( res ){
  if( res.exists ){
    console.log('文件存在');
  }else{
    console.log('文件不存在');
  }
});
@endsection

kk.file.remove(filepath, [done], [fail])

删除文件,接收一个描述文件路径的字符串 filepathdone 表示成功回调,fail 表示失败回调。

filepath

类型: string
文件路径

done

类型: function,可选
成功回调

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 不能访问指定的路径
2 文件不存在
9 删除失败
@section('删除文件示例代码')
//删除文件
kk.file.remove('sdcard://kktest/fileTest.txt', function(){
  console.log('删除文件成功');   
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.file.view

该能力有两种调用形式:

  • kk.file.view(filepath, [done], [fail]) 查看文件(简写形式),只传递链接地址或文件路径,其他参数使用默认配置;
  • kk.file.view(options, [done], [fail]) 查看文件(配置形式),不仅传递文件路径,还传递详细参数配置

filepath

类型: string
文件路径,或链接地址

options

类型: object
配置参数对象

options.filepath

类型: string
文件路径

options.via

类型: string
使用什么方式查看,可选值有三个,默认是 auto

  • auto
  • wps
  • webview

options.mode

类型: string
文件打开的方式,可选值有两个,默认是 readonly

  • readonly(只读)
  • edit(编辑)

options.title

类型:string
页面上的标题,此参数仅在使用webview(KK客户端)打开时有效

options.mimeType

类型: string
文件的类型,如果不传,从文件名分析

done(args)

类型: function,可选
成功回调

注: 用户使用 WPS 查看文档时, 对文档进行打开、保存及关闭操作均会触发成功回调。

args.filepath

类型: string
文件的相对路径

args.operation

类型: string
对文档的操作类型,仅在调用能力时传递了via参数并且值是 wps,才会返回该值,并且只返回该值。

  • open:打开文档;
  • save:保存文档;
  • close:关闭文档;

注: 若文档在 WPS 中编辑时多次保存,则会多次触发成功回调,且 args.operation 均为 save

args.mimeType

类型: string
文件的类型(仅在调用能力时参数 filepath是链接(url)或者配置形式传递了mimeType参数,才会返回该值)

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 文件不存在
-2 未安装wps
-3 文档保存失败
-6 wps发生错误

补充

android设备

  • 在简写形式下,如果传的filepath是链接形式(例如:http://www.baidu.com),则一定是用webview方式打开;如果传的filepath是路径形式,则是用外部应用方式打开;

  • 在配置形式下,如果没有传via参数,都是以外部应用方式打开

ios设备:参数如果没有传via参数, 则会根据路径kk控制台-系统管理-基础功能配置-IOS客户端文件打开配置-打开方式 去打开文件

二者(android设备&&ios设备):参数传via参数,都是会以via参数对应的方式去打开文件

(附ios配置方式在控制台的地址:)

ios-fileView

@section('查看链接')
//查看链接(简写形式)
kk.file.view('http://kk5.landray.com.cn:6789/', function (res) {
  console.log('查看链接');
}, function (code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
//等同于 =>
//查看链接(配置形式)
kk.file.view({
  filepath: 'http://kk5.landray.com.cn:6789/',
  via: 'webview'  // 使用webview查看链接
}, function (res) {
  console.log('查看链接');
}, function(code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection
@section('根据路径查看文件')
//根据路径查看文件(简写形式)
kk.file.view('sdcard://kktest/fileTest.txt', function () {
  console.log('在Andriod设备下直接使用外部应用打开文件,在IOS设备下则根据控制台配置的打开方式打开');
}, function (code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection
@section('使用wps查看本地文件')
//查看文件(配置形式)
kk.file.view({
  filepath: 'sdcard://kktest/fileTest.txt',
  via: 'wps',  // 使用wps方式查看
  mode: 'readonly' // 只读模式
}, function (res) {
  console.log(res.operation); // 使用wps方式查看文件,回调只返回operation字段
}, function(code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.file.readAsText

该能力有两种调用形式:

  • kk.file.readAsText(filepath, done, [fail]) 直接读取文件内容

  • kk.file.readAsText(options, done, [fail]) 配置相关参数读取文件内容

filepath

类型: string
文件路径

options

类型: object
包含文件路径以及编码方式的对象,默认'utf-8'方式编码

options.encoding

类型: string
编码方式

options.filepath

类型: string
文件路径

done(args)

类型: function
成功回调

args.content

类型: string
接收有 content 属性的对象作为参数,content 为文本内容

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 文件不存在
9 没有查看权限
@section('直接读取文件内容')
//直接读取文件内容
kk.file.readAsText('sdcard://kktest/fileTest.txt', function (res) {
  console.log('文本内容:' + res.content);
}, function (code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection
@section('配置参数读取文件内容')
//根据编码读取文件内容
kk.file.readAsText({
  encoding: 'BIG5', // 选填,默认为utf-8
  filepath: 'sdcard://kktest/fileTest.txt'
}, function (res) {
  console.log('文本内容:' + res.content);
}, function (code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.file.readAsBase64(filepath, done, [fail])

读取文本文件内容,将文件转换base64字符串

filepath

类型: string
文件路径

done(args)

类型: function
成功回调

args.content

类型:string
接收有content属性的对象作为参数,content为base64字符串

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 文件不存在
-9 文件路径为目录(仅限android)
@section('将文件转换base64字符串示例代码')
// 读取文件内容
kk.file.readAsBase64('sdcard://kktest/fileTest.jpg', function(res){
  var imgData = 'data:image/jpeg;base64,' + res.content;
  // 在此即可将图片的src设置为 imgData, 图片即可显示
}, function(code, msg){
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.file.copy(options, [done], [fail])

拷贝文件(IOS可以拷贝文件,文件夹;Android可以拷贝文件,但不能拷贝文件夹)

options

类型: object
包含源文件路径及目标路径的对象

options.source

类型:string 源文件路径,必填

options.target

类型:string 目标的路径,必填

done

类型: function,可选
成功回调,没有回调参数

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 文件不存在
9 文件拷贝发生错误
@section('拷贝文件示例代码')
//拷贝文件
kk.file.copy({
  source: 'sdcard://kktest/test.txt',
  target: 'sdcard://kktest/file/test.txt'
}, function () {
  console.log('拷贝文件成功');
}, function (code, msg) {
  console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

定位模块

封装了地理定位的能力

kk.location.getLocation(done, [fail])

获取当前位置的坐标信息,包括经度、纬度、海拔

done(args)

类型: function
成功回调,接收一个对象 args 作为参数

args.longitude

类型: string
经度

args.latitude

类型: string
纬度

args.altitude

类型: string
海拔

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
3 参数非法
9 没有开启定位功能
@section('获取当前位置示例代码')
//获取当前位置
kk.location.getLocation( function( res ){
    /* res 值示例
    {
      longitude:'113.946687',//经度
      latitude:'22.546562',//纬度
      altitude:'4.9E-324'//altitude
    }
    */
});
@endsection

历史记录模块

历史记录模块,提供操作webview历史记录的能力(前进、后退等)

kk.history.canGo(done)

获取当前页面是否可以进行前进及后退操作

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.canGoBack

类型: boolean
是否能够后退

args.canGoForward

类型: boolean
是否能能够前进

@section('判断是否可以前进及后退示例代码')
//判断是否可以前进及后退 
kk.history.canGo(function( res ){ 

    if( res.canGoBack ){
        console.log('页面可后退')
    }else{
        console.log('页面不可后退')
    }

    if( res.canGoForward ){
        console.log('页面可前进');
    }else{
        console.log('页面不可前进');
    }
});
@endsection

kk.history.hasPrev(done)

判断当前页面是否有上一页

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.hasPrev

类型: boolean
是否有上一页,true 为有上一页

@section('判断是否有上一页示例代码')
//判断是否有上一页 
kk.history.hasPrev(function(res){
    if(res.hasPrev){
        console.log('页面有上一页');
    }else{
        console.log('页面没有上一页');
    }
});
@endsection

kk.history.back([fail])

返回到上一页

fail

类型: function,可选
失败回调,如果没有上一页,则会调用该函数,该函数不接受参数

@section('返回上一页示例代码')
//返回上一页
kk.history.back( function(){
    console.log('当前页不能做返回操作');
});
@endsection

kk.history.forward([fail])

前进到下一页

fail

类型: function,可选
失败回调,如果没有下一页,则会调用该函数,该函数不接受参数

@section('前往下一页示例代码')
//前进下一页
kk.history.forward( function(){
    console.log('当前页不能做跳转下一页操作');
});
@endsection

扫描器模块

扫描器模块提供扫描二维码、条形码及生成二维码的能力

kk.scaner.scanBarCode(done, [fail])

扫描条形码

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.code

类型: string
条形码的内容

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 用户取消
-10000 设备没有权限(仅限android, IOS没有提示)
1 设备不支持
@section('扫描条形码示例代码')
//扫描条形码
kk.scaner.scanBarCode(function(res){
    /*res 值示例
    {
        retCode:0,
        code:'http://baike.baidu.com'//条形码内容
    }
    */
});
@endsection

kk.scaner.scanTDCode(done, [fail])

扫描二维码

done(args)

类型: function
成功回调,返回一个对象 args 作为参数

args.code

类型: string
二维码的内容

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 用户取消
-10000 设备没有权限(仅限android, IOS没有提示)
1 设备不支持
@section('扫描二维码示例代码')
//扫描二维码
kk.scaner.scanTDCode(function(res){
    console.log('二维码内容:' + res.code);
});
@endsection

kk.scaner.getQRCode(options, [done], [fail])

生成二维码图片,图片格式为png

options

类型: object
生成二维码的配置项

options.content

类型: string
二维码内容

options.targetSize

类型: number
输出的正方形图片的边长,范围:50-800

options.destinationType

类型: string,可选值:file/data
文件输出形式

options.savePath

类型: string
输出类型为file时有效,不指定则随机文件名保存至 sdcard://easymi/ 目录下

done(args)

类型: function,可选
成功回调,返回一个对象 args 作为参数

args.imageURI

类型: string
处理后的文件保存路径(当destinationType为file时,返回此属性)

args.imageFileOSPath

类型: string
处理后的文件的操作系统路径(当destinationType为file时,返回此属性)

args.imageData

类型: string
图片内容的base编码(当destinationType为data时,返回此属性)

fail

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
9 生成失败
999 参数错误
@section('生成二维码示例代码')
//生成二维码
kk.scaner.getQRCode({
    content: '蓝凌软件股份有限公司',
    targetSize: 100,
    destinationType: 'file',
    savePath: 'sdcard://easymi/1.png'
}, function(res){
    /* res 值示例
    {
     imageURI:'sdcard://easymi/1.png',//二维码处理后的文件保存路径
     imageFileOSPath:'kkapp://fil.o-1091-o.kk/storage/sdcard1/easymi/1.png'//二维码处理后的文件的操作系统路径   
    }
    */
}, function(code, msg){
    console.log('错误信息:' + msg + ',错误代码:' + code);
});
@endsection

kk.scaner.scanIDCard([options], done, [fail])

身份证扫描识别

options

类型: object,可选
提示信息的配置项

options.hint

类型: string 扫描界面上的提示信息

done(args)

类型: function 成功回调,返回一个对象 args 作为参数(如果扫描的是身份证的正面,反面信息也会返回,但是是以空字符串形式返回;如果扫描的是身份证的反面,正面信息也会返回,同样也是以空字符串返回)

args.isFront

类型: boolean
当前扫描的是否为身份证正面,true 即为正面

args.name

类型: string
姓名(仅扫描正面时该字段有值)

args.sex

类型: string
性别(仅扫描正面时该字段有值)

args.national

类型: string
民族(仅扫描正面时该字段有值)

args.birthday

类型: string
生日, 格式和身份证上面的一样 (仅扫描正面时该字段有值)

args.address

类型: string
住址(仅扫描正面时该字段有值)

args.idcard

类型: string
身份证号码(仅扫描正面时该字段有值)

args.issue

类型: string
签发机构(仅扫描反面时该字段有值)

args.validity

类型: string
身份证有效期(仅扫描反面时该字段有值)

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 能力未获得授权,无法使用。若提示该错误信息,请联系蓝凌KK事业部
-2 用户取消
-8 没有相机权限
-9 OCR程序出错
@section('扫描身份证示例代码')
// 扫描身份证
kk.scaner.scanIDCard({
  hint: '请扫描身份证'
}, function(res){
  /*res值示例
   * 扫描正面时的示例
    {
      "isFront": true, // 正面
      "name":"庞玲", // 姓名
      "sex":"女", //性别
      "national":"汉", //民族
      "birthday":"1989年9月20日", //生日
      "address":"安徽省蒙城县乐生镇杨桥村武庄62号", // 住址
      "idcard":"341234198909204160", //身份证号码
      "issue":"",  //签发机构
      "validity":"" //身份证有效期
    }

    * 扫描反面时的示例
    {
      "isFront": false,
      "name": "",
      "sex": "",
      "national": "",
      "birthday": "",
      "address": "",
      "idcard": "",
      "issue": "町县公安局",
      "validity": "2009.12.21-2029.12.21"
    }
  */
  console.log(res);
}, function(code, msg){
  console.log('扫描身份证错误信息:' + msg + ', 错误代码:' + code);
})
@endsection

kk.scaner.scanVLCard([options], done, [fail])

车辆行驶证扫描识别

options

类型: object,可选
提示信息的配置项

options.hint

类型: string 扫描界面上的提示信息

done(args)

类型: function 成功回调,返回一个对象 args 作为参数

args.plateNo

类型: string
车辆号牌号码

args.type

类型: string
车辆类型

args.owner

类型: string
车辆所有人

args.address

类型: string
住址

args.useCharacter

类型: string
车辆使用性质

args.model

类型: string
车辆品牌型号

args.vin

类型: string
车辆识别代号

args.engineNo

类型: string
车辆发动机号码

args.registerDate

类型: string
行驶证注册日期。格式和证件上一样。

args.issueDate

类型: string
行驶证发证日期。格式和证件上一样。

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 能力未获得授权,无法使用。若提示该错误信息,请联系蓝凌KK事业部
-2 用户取消
-8 没有相机权限
-9 OCR程序出错
@section('扫描车辆行驶证示例代码')
// 扫描车辆行驶证
kk.scaner.scanVLCard({
  hint: '请扫描车辆行驶证'
}, function(res){
  /*res值示例
    {
      plateNo: "京BU89ED", //车辆号牌号码
      type: "小型轿车", //车辆类型
      owner: "焦西杰", //车辆所有人
      address: "河南省腾山市丰风区右家坞镇石嘉窝村塘五区11籍41号", // 住址
      useCharacter: "非营运", // 车辆使用性质
      model: "大众牌PV7126VOMUQQ", //车辆品牌型号
      vin: "PV2B1107F87369479", // 车辆识别代号
      engineNo: "Y26549", //车辆发动机号码
      registerDate: "2016-01-08", //行驶证注册日期
      issueDate: "2016-01-08"  //行驶证发证日期
    }
  */
   console.log(res);
}, function(code, msg){
  console.log('扫描车辆行驶证错误信息:' + msg + ', 错误代码:' + code);
})
@endsection

分享模块

封装了分享消息至指定客户端(如微信好友, kk等)的功能

kk.share.to

该能力有三种调用方式:

  • kk.share.to(dest, [done], [fail])
    分享到客户端当前链接。
    若当前应用为在线应用,则分享当前页面链接;
    若当前应用为混合应用,则会调用内部 getAppShareLink 方法获取当前应用的链接

  • kk.share.to(dest, url, [done], [fail])
    分享指定的链接

  • kk.share.to(dest, options, [done], [fail])
    根据配置进行分享,若分享文本消息至 kk 时, options可简写成文本消息字符串

dest

类型: string
指定的客户端,目前可选值有 weixin (微信好友), kk (同事)

url

类型: string,可选
指定要分享的链接

options()

类型: object
相关参数,分享至weixinkk参数不同

options(weixin)

options.url

类型: string,可选
卡片式消息的链接, 不填写则默认分享当前页面

options.title

类型: string,可选
卡片式消息的标题

options.content

类型: string, 选填
卡片式消息的摘要

options.imageUri

类型: string, 选填
分享缩略图。支持http(s)协议,以及KK协议路径。如果不填则分享链接里面获取, 微信缩略图大小限制为32KB。

options(kk)

options.type

类型: string,可选
指定消息类型,可选值有 text (文本消息), card (卡片消息),默认值为 card

options.url

类型: string
type为 card 时必填,卡片式消息的链接

options.title

类型: string
type为 card 时必填,卡片式消息的标题

options.content

类型: string
必填,type为 text 时表示文本消息正文,type为 card 时表示卡片消息的摘要

options.imageUri

类型: string
选填,卡片式消息图标

options.recieverType

类型: string
当recieverList有值时必填,指定接收方类型,可选值有 user (同事), group (群组)

options.recieverList

类型: string|array
选填,接收方列表,列表内容为接收方的ID,即如果recieverType为 user 时,列表各项内容为相应的userID

options.showChooseView

类型: boolean
选填,是否手动选择接收者。若该值为 true,则会拉起选人界面; 若该值为 false,且在recieverList指定了接收者,则会直接发送消息。默认为 true

done

类型: function,可选
成功回调

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 页面不能分享
2 分享被外部系统拒绝
9 发生其他错误
-1 用户取消
-2 网络连接不可用
-6 参数错误
@section('分享当前链接至微信')
// 方法内部会自动判断当前应用类型,
// 若应用类型为混合应用,则会调用内部getAppShareLink方法获取应用的链接地址
// 若应用类型为在线应用,则分享的链接为当前页面的链接地址,即location.href
kk.share.to('weixin', function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection
@section('分享链接至微信好友')
//分享链接至微信好友
kk.share.to('weixin', 'http://kk5.landray.com.cn:6789/', function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
//等同于 =>
kk.share.to('weixin', {
  url: 'http://kk5.landray.com.cn:6789/'
}, function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection
@section('分享当前链接至KK')
// 方法内部会自动判断当前应用类型,
// 若应用类型为混合应用,则会调用内部getAppShareLink方法获取应用的链接地址
// 若应用类型为在线应用,则分享的链接为当前页面的链接地址,即location.href
kk.share.to('kk', function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection
@section('分享链接至KK')
//分享链接至KK
kk.share.to('kk', 'http://kk5.landray.com.cn:6789/', function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
//等同于 =>
kk.share.to('kk', {
  url: 'http://kk5.landray.com.cn:6789/',
  type: 'card'
}, function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection
@section('分享文本消息至KK')
//分享文本消息至KK
kk.share.to('kk', '一条文本消息', function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
//等同于 =>
kk.share.to('kk', {
  content: '一条文本消息',
  type: 'text'
}, function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection
@section('分享文本消息至指定的KK同事')
//分享至KK时,默认的流程是需要进行选择接收的人员,可通过以下配置直接发送
//该示例演示的是直接发送文本消息,应用消息类同
kk.share.to('kk', {
  content: '一条文本消息',
  type: 'text',
  showChooseView: false,
  recieverType: 'user',
  recieverList: [200000, 200003]
}, function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection

kk.share.appMessage(options, [done], [fail])

分享应用至KK

options

类型: object
相关参数

options.data

类型: object
选填,附带参数。通过分享的应用消息进入应用后,可在 kk.ready 的参数中获取data的内容

options.title

类型: string
必填,消息标题

options.content

类型: string
必填,消息摘要

options.targetPlatform

类型: string
选填,可打开该应用的目标平台,可选值有 ios (iOS系统), android (安卓系统), mobile (移动端), desktop (PC端), universal (所有平台),默认值为 mobile

options.targetType

类型: string
选填,目标平台类型,可选值有 pad (平板类), phone (手机类), universal (通用类),默认值为 universal

options.recieverType

类型: string
当recieverList有值时必填,指定接收方类型,可选值有 user(同事), group (群组)

options.recieverList

类型: string|array
选填,接收方列表,列表内容为接收方的ID,即如果recieverType为 user 时,列表各项内容为相应的userID

options.showChooseView

类型: boolean
选填,是否手动选择接收者。若该值为 true,则会拉起选人界面; 若该值为 false,且在recieverList指定了接收者,则会直接发送消息。默认为 true

done

类型: function,可选
成功回调

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
1 页面不能分享
2 分享被外部系统拒绝
9 发生其他错误
-1 用户取消
-2 网络连接不可用
-6 参数错误
@section('分享应用至KK示例代码')
//分享应用至KK,该方法分享的消息固定为卡片消息
//调用此方法时,会自动通过内部方法getAppShareLink获取应用的链接,然后通过to方法发送卡片消息
kk.share.appMessage({
  data: {
    x: 'data的内容可通过分享的应用消息进入应用后,在kk.ready的参数中获取'
  },
  title: '分享的标题',
  content: '分享的内容'
}, function () {
  console.log('分享成功');
}, function (code, msg) {
  console.log('错误代码:' + code + '; 错误详情:' + msg);
});
@endsection

kk.share.getAppShareLink([options])

获取分享链接

options:

类型: object,可选
相关参数

options.data

类型: object
选填,附带参数。通过分享的应用消息进入应用后,可在 kk.ready 的参数中获取data的内容

options.targetPlatform

类型: string,可选,可选值有iosandroidmobiledesktopuniversal,默认值 mobile
选填,可打开该应用的目标平台,可选值有 ios (iOS系统), android (安卓系统), mobile (移动端), desktop (PC端), universal (所有平台)

options.targetType

类型: string,可选,可选值有padphoneuniversal,默认值为 universal
选填,目标平台类型,可选值有 pad (平板类), phone (手机类), universal (通用类)

@section('获取分享链接示例代码')
//获取当前应用的链接
var link = kk.share.getAppShareLink({
  data: {
    msg: 'data的内容可通过分享的应用消息进入应用后,在kk.ready的参数中获取'
  }
});
console.log('链接为:' + link);
@endsection

菜单模块

menu模块,提供了对webview右上角的菜单项的相关能力,如显示或隐藏菜单项、分享等等

kk.menu.showMenuItems()

显示应用容器(webview)右上角的菜单项

@section('显示右上角菜单项示例代码')
kk.menu.showMenuItems();
@endsection

kk.menu.hideMenuItems()

隐藏应用容器(webview)右上角的菜单项

@section('隐藏右上角菜单项示例代码')
kk.menu.hideMenuItems();
@endsection

支付模块

支付能力模块 提供了向第三方支付的能力,目前仅限ios平台

kk.pay.weixin(options, done, [fail])

微信支付API

options

类型: object
配置项

options.appid

类型: string
微信开放平台审核通过的应用APPID。必填

options.partnerid

类型: string
微信支付分配的商户号。必填。

options.prepayid

类型: string
微信返回的支付交易会话ID。必填。

options.package

类型: string,固定值Sign=WXPay
暂填写固定值Sign=WXPay。必填。

options.noncestr

类型: string
随机字符串,不长于32位。必填。

options.timestamp

类型: string
时间戳,标准北京时间,自1970年1月1日 0点0分0秒以来的秒数。必填。

options.sign

类型: string
签名,详见微信支付官网上的签名算法 微信支付签名算法

done

类型: function
成功回调 ,没有回调参数

fail(code,msg)

类型: function,可选
失败回调

code

类型: number
错误代码

msg

类型: string
错误信息

错误代码 错误信息
-1 微信拒绝发起支付(一般是由于接入信息不正确、签名不正确等)
-2 用户取消
-3 设备上未安装微信
@section('发起微信app支付示例代码')
kk.pay.weixin({
  appid: 'wx0aee55eb7d35b42b', // 你的appid,需要自己申请
  partnerid: '1229457302', // 商户号id
  prepayid: '12294573232', // 交易会话id
  package: 'Sign=WXPay',//固定值Sign=WXPay
  noncestr: 'Wm3WZYTPz0wzccnW',
  timestamp: '1477460765018',
  sign: '0f9de62fce790f9a083d5c99e95740ceb90c27ed'
}, function(){
}, function( code, msg){
  console.log('微信app支付失败回调 code: ' + code +' ,msg: ' + msg );
});
@endsection

工具模块

工具模块提供了一些常用的工具函数。

kk.untils.type

该能力有两种调用形式:

  • kk.utils.type(obj) 判断参数类型,传递一个参数obj,返回obj的数据类型

  • kk.utils.type(obj, type) 判断参数类型。传递两个参数 objtype,判断obj的数据类型是否等于type,如果等于返回 true,否则返回 false

特殊情况:

kk.utils.type() => 返回undefined
kk.utils.type(null) => 返回null
kk.utils.type(undefined) => 返回undefined
kk.utils.type(NaN) => 返回Number

@section('判断参数类型:不传type')
//不传递type:获取参数的数据类型
kk.utils.type(123);//=> Number
@endsection
@section('判断参数类型:传type')
//传递type:判断参数类型是否正确
kk.utils.type('obj', 'String');//=> true
@endsection

kk.utils.isArray(arr)

判断变量是否为数组

arr

类型: Any(string,boolean,object,array,function,number)
要判断的变量,若是数组返回 true,否则返回 false

@section('判断变量是否为数组示例代码')
//判断变量是否为数组 
kk.utils.isArray([1,2,3]);//=> true
kk.utils.isArray('[1,2,3]');//=> false
@endsection

kk.utils.isWindow(obj)

判断变量是否为window对象

obj

类型: Any(string,boolean,object,array,function,number)
要判断的变量,若是window对象返回 true,否则返回 false

@section('判断变量是否为window对象示例代码')
//判断变量是否为window对象
kk.utils.isWindow(window);//=> true
@endsection

kk.utils.isObject(obj)

判断参数是否为对象

obj

类型: Any(string,boolean,object,array,function,number)
要判断的变量,若是对象返回 true,否则返回 false

@section('判断参数是否为对象示例代码')
//判断参数是否为对象 
kk.utils.isObject('obj');//=> false
kk.utils.isObject({});//=> true
@endsection

kk.utils.isPlainObject(obj)

判断变量是否为简单对象(即JSON格式对象)

obj

类型: Any(string,boolean,object,array,function,number)
要判断的变量,若是JSON格式对象返回 true,否则返回 false

@section('判断变量是否为简单对象示例代码')
//判断变量是否为简单对象 
kk.utils.isPlainObject({"obj": "KK sdk 参考手册"});//=> true
@endsection

kk.utils.isEmpty(obj)

判断参数是否为空,为空则返回 true, nullundefined[](空数组)及 ''(空字符串)被判断为空

obj

类型: Any(string,boolean,object,array,function,number)
要判断的变量,若是空返回 true,否则返回 false

@section('判断参数是否为空示例代码')
//判断参数是否为空 
kk.utils.isEmpty(null);//=> true
kk.utils.isEmpty('');//=> true
kk.utils.isEmpty([]);//=> true

kk.utils.isEmpty(0);//=> false
@endsection

kk.utils.isFunction(fn)

判断变量是否为函数

fn

类型: Any(string,boolean,object,array,function,number)
要判断的变量,若是函数返回 true,否则返回 false

@section('判断变量是否为函数示例代码')
var bar = '';
function foo(){};
//判断变量是否为函数 
kk.utils.isFunction(bar);//=>false
kk.utils.isFunction(foo);//=>true
@endsection

kk.utils.extend([deep], [dest], source, [source...], [ride])

扩展对象

deep

类型: boolean,可选,默认 false
是否深度拷贝

dest

类型: object,可选
要扩展的对象,如果省略则扩展调用环境(context)

source

类型: object,可选
要扩展的属性来源,可支持多个source

ride

类型: boolean,默认 true
是否覆盖已有属性

return(args):

args :返回扩展之后得到的对象

@section('扩展对象示例代码')
var dest =  {a: 1};
var source1 = {
    a: 11,
    b: 22,
};
var source2 = {
    a: 111,
    b: 222,
    c: 333
};
//默认扩展
kk.utils.extend(dest, source1);
//dest = {a: 11, b: 22}
//不覆盖已有属性
kk.utils.extend(dest, source1, false);
//dest = {a: 1, b: 22}
//扩展多个属性来源,且不覆盖已有属性
kk.utils.extend(false, dest, source1, source2, false);
//dest = {a: 1, b: 22, c: 333}
@endsection

kk.utils.toQueryString(obj)

将对象转换为queryString。将对象中的key和value作为URI组件进行编码,返回转换后的queryString。

obj

类型: object
需要转换的对象

return(arg):

返回由key=value组成的string字符串,每个键值对由&分隔

@section('转换对象示例代码')
var obj = {version: 'kk sdk 5.0', anthor: 'landray'};

//将对象转换为queryString
kk.utils.toQueryString(obj);
//返回字符串。=> 'version=kk%20sdk%205.0&anthor=landray'
@endsection

kk.utils.splitURI(str)

快速解析出URI的各个部分,包括 scheme(比如 http, ftp, mailto), authority(比如 localhost, www.baidu.com, kk5.landray.com.cn:6789), path(比如 /search), query(查询字符串,比如 keyword=kk&pageNo=1&pageSize=10), fragment(锚点,比如 install),调用该函数会返回一个数组,数组下标的 1~5 分别代表上述信息(URI部分信息缺失时,缺失的部分为空字符串或undefined)。使用该函数前需保证 str 是一个合法的 URI (可用 kk.utils.isURIkk.utils.isURL 判断), 否则解析得到的信息无效。

str

类型: string
需要解析的字符串

@section('解析URL')
var url = 'https://www.google.com.hk/search?q=kk#newwindow=1&safe=strict';
var urlParts = []
if(kk.utils.isURL(url)) {
    urlParts = kk.utils.splitURI(url);
    // urlParts[1] 为 https (表示 scheme)
    // urlParts[2] 为 www.google.com.hk (表示 authority)
    // urlParts[3] 为 /search (表示 path)
    // urlParts[4] 为 q=kk (表示 query)
    // urlParts[5] 为 newwindow=1&safe=strict (表示 fragment)
}
@endsection

kk.utils.isURI(str)

判断 str 是否为一个合法的URI(详见URI规范),若为合法的URI则返回 true ,否则 false. URI的例子可参见rfc3986

str

类型: string
需要判断的字符串

@section('判断字符串是否为URI')
kk.utils.isURI('ftp://ftp.is.co.za/rfc/rfc1808.txt');
// 返回 true
kk.utils.isURI('tel:+1-816-555-1212');
// 返回 true
kk.utils.isURI('call-weixin');
// 返回false
@endsection

kk.utils.isURL(str)

判断 str 是否为一个合法的浏览器网址,若为合法的网址则返回 true ,否则 false。URL 是 URI的子集, 即若字符串是URL则一定是URI。

str

类型: string
需要判断的字符串

@section('判断字符串是否为URL')
kk.utils.isURL('http://www.google.com');
// 返回 true
kk.utils.isURL('abc');
// 返回 false
@endsection

兼容微信的能力模块

兼容微信JS_SDK能力的模块,目前仅兼容微信和kk共有的能力,能力调用方式和微信一致

kk.wx.ready(fn)

wx的ready,兼容微信,区别在于回调函数多了参数

fn

类型: function
成功回调

@section('准备调用微信API示例代码')
//wx的ready
wx.ready(function(){
  console.log('准备调用微信API');
});
@endsection

kk.wx.checkJsApi(options)

检查是否支持该能力,完全兼容

options

类型: object
配置选项,详见options

options.jsApiList

类型: array
要检查是否支持的能力名称

options.success(args)

类型: function
成功回调,返回一个对象作为参数,详见args

args.checkResult

类型: object
以键值对的形式返回json形式的object,可用的api值 true,不可用为 false

args.errMsg

类型: string
错误信息



3/23/2017 10:40:59 AM 3/23/2017 10:41:00 AM

@section('能力支持检查示例代码')
//能力支持检查
kk.wx.checkJsApi({
  jsApiList: ['chooseImage'],
  success: function(res) {
    // 以键值对的形式返回,可用的api值true,不可用为false
    console.log(JSON.stringify(res));
    // 如:{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
  }
})
@endsection

kk.wx.previewImage(options)

预览图片,目前仅支持预览本地图片

options

类型: object
调用参数,详见options

options.current

类型: string
当前显示图片的地址

options.urls

类型: array
需要预览的图片地址列表

@section('预览图片示例代码')
// 预览图片
kk.wx.previewImage({
    current: 'sdcard://1.jpg',
    urls: [ 'sdcard://1.jpg', 'sdcard://2.jpg', 'sdcard://3.jpg']
});
@endsection

kk.wx.startRecord()

开始录音,完全兼容

@section('微信录音示例代码')
//录音
kk.wx.startRecord();
@endsection

kk.wx.stopRecord(options)

停止录音,兼容微信,但是参数不一致。

options

类型: object
调用参数

options.success

类型: function
用户停止录音后的回调函数,返回的参数与captureAudio一致

@section('停止微信录音示例代码')
//停止录音
kk.wx.stopRecord({
  success: function(res){
    /*res 值示例
    {
      name:'ekp_1488265458521',
      fullPath:'/data/data/com.landray.kkplus/files/ekp_1488265458521.amr',
      type:'audio/amr',
      size:13478
    }
    */
    //用户停止录音后执行的回调函数
    console.log(JSON.stringify(res));
    console.log('录音文件路径:' + res.fullPath);
  }
});
@endsection

kk.wx.onVoiceRecordEnd(obj)

录音自动结束事件,微信有录音1分钟的限制,kk没有,提供此函数仅为兼容,没有实际作用

@section('微信录音示例代码')
//录音
kk.wx.onVoiceRecordEnd();
@endsection

kk.wx.playVoice(options)

播放语音

options

类型: object
调用参数

options.localId

类型: string
语音地址。此处得传kk约定的音频文件路径

@section('播放语音示例代码')
//播放语音
kk.wx.playVoice({
  localId: '' // 此处得传kk约定的音频文件路径
});
@endsection

kk.wx.getNetworkType(options)

获取当前网络类型,完全兼容微信

options

类型: object
调用参数

options.success(args)

类型: function
回调函数,返回一个对象 args 作为参数

args.networkType

类型: string
返回网络类型:空字符串,2G,3G(iOS下2G/3G均返回3G),4G,WIFI

@section('获取当前网络类型示例代码')
//获取当前网络类型 
kk.wx.getNetworkType({
  success: function(res){
    var networkType = res.networkType; 
    // 返回网络类型:空字符串,2G,3G(iOS下2G/3G均返回3G),WIFI
    console.log('获取当前网络类型:' + networkType);
  }
});
@endsection

kk.wx.getLocation(options)

wx获取当前位置,兼容微信,缺少部分数据。返回参数与kk.location.getLocation一致

options

类型: object
调用参数

options.success(args)

类型: function
回调函数,返回一个对象 args 作为参数

args.latitude

类型: string
纬度

args.longitude

类型: string
经度

args.altitude

类型: string
海拔

@section('微信获取当前位置示例代码')
//获取当前位置
kk.wx.getLocation({
  success: function(res){
    console.log( '纬度:' + res.latitude );
    console.log( '经度:' + res.longitude );
    console.log( '海拔:' + res.altitude );
  }
});
@endsection

kk.wx.closeWindow()

关闭窗口(退出应用),完全兼容微信

@section('退出应用示例代码')
//退出应用
kk.wx.closeWindow();
@endsection

kk.wx.scanQRCode(options)

扫描二维码,部分兼容

options

类型: object
配置选项

options.needResult

类型: number
只支持 needResult 为1,直接返回扫描结果

options.scanType

类型: string
可以指定扫二维码还是一维码,默认二者都有

options.success(args)

类型: function
回调函数,返回一个对象 args 作为参数

args.resultStr

类型: object
二维码的内容

@section('扫描二维码示例代码')
//扫描二维码
kk.wx.scanQRCode({
  needResult: 1,//只支持 needResult 为1
  scanType: 'barCode',
  success: function(res){
    console.log('扫描结果:' +  res.resultStr);
    //=>{"resultStr": "http://baidu.com"}
  }
})
@endsection

友情链接: 微信JS-SDK说明文档

对应代码 接口
chooseImage 拍照或从手机相册中选图接口
previewImage 预览图片接口
uploadImage 上传图片接口
downloadImage 下载图片接口

JS SDK版本变更记录

v1.2.41@2017-07-5.适用的客户端版本6.0

  • 修改 proxy.vueInterceptor, 默认将返回的数据当作 JSON 处理,优化对vue-resouce中 params 参数的处理(作为URL的query string处理)

v1.2.39@2017-07-3.适用的客户端版本6.0

  • 增加 app.setScreenMode, 允许设置应用显示为全屏模式
  • 修改 phone.call 可通过传递参数 needCallSessionInfo 来记录会话相关信息

v1.2.35@2017-06-1.适用的客户端版本6.0

  • 增加 kk.defy, 可以将KK能力 promise 化

v1.2.30@2017-05-19.适用的客户端版本6.0

  • 增加 kk.scaner.scanIDCard 可以扫描并识别身份证信息,客户端打包时需提供正确的 合合OCR SDK 密钥, 否则将无法调用改能力
  • 增加 kk.scaner.scanVLCard 可以扫描并识别扫描车辆行驶证信息,客户端打包时需提供正确的 合合OCR SDK 密钥, 否则将无法调用改能力
  • 增加 kk.device.getOrientation 可获取屏幕旋转方向的配置策略
  • 优化 kk.device.setOrientation 支持设置屏幕自动旋转
  • 优化 kk.file.view 支持使用WSP查看并编辑文档
  • 优化 kk.econtact.choosekk.econtact.getUserInfo 获取到的用户信中增加 jobTitle(职位名称) 及 signature(个性签名)
  • 优化 kk.media.previewImage 在预览图片时支持分额外操作:保存到相册, 分享到微信

v1.2.22@2017-04-25.适用的客户端版本5.2.6.3

  • 调整: 调用kk.app.on 对同一个应用事件绑定多个处理函数时,只要其中任一函数返回了 false 则立即停止执行后续的回调函数

v1.2.17@2017-04-20.适用的客户端版本5.2.6.3

  • 能力 kk.app.on 支持同一个应用事件绑定多个处理函数
  • 增加 kk.app.off(eventName, cb) 取消某函数对应用事件的监听

v1.2.13@2017-04-07.适用的客户端版本5.2.6.2

  • 增加 kk.utils.renameKeys 可用于重命名对象键名
  • 增加 kk.econtact.showECard 可用于显示联系人资料卡片
  • 使用 kk.utils.renameKeys 调整 kk.econtact.startChat 参数命名为 {userID: 'xxx', loginName: 'xxxx'},,统一能力参数. kk.app.callAppkk.app.getDeviceInfo 也使用改函数重新调整
  • kk.media.getPicture 支持拍摄选取多张图片,通过新增参数 count 来设置数量,多张不支持Base64

v1.2.6@2017-04-01.适用的客户端版本5.2.6.2

  • kk.app.getClientInfo 返回的信息增加 lang(客户端语言), webServer(KK Web Server地址)

v1.2.5@2017-03-30.适用的客户端版本5.2.6.2

  • 增加 kk.econtact.startChat,可用于发起和某用户的会话,并可以携带相关聊天文字(文字在输入框中,并不会直接发送出去)

v1.2.4@2017-03-24.适用的客户端版本5.2.6.1

  • 修正 kk.utils.isURL 不能正确判断 URL的问题,修改后支持 规范rfc3986 定义的URL 格式
  • 增加 kk.utils.isURI, 可用于判断字符串是否为合法 URI
  • 增加 kk.utils.splitURI, 可用于快速解析 URI的 scheme(如协议 http, ftp), authority(比如 host, ip 等), path, query(查询字符串), fragment(锚点)
  • 修正 promise 库中的 deferred.always 的拼写错误

v1.2.1@2017-03-22.适用的客户端版本5.2.6.1

  • 修正 kk.app.callApp 的第二个参数为 null 时(如 kk.app.callApp('kk-mail', null, function(){})), 将 null 当作 args 处理的问题。修正后,第二个参数为空时当作不传 成功回调(即当作参数 done 处理)。

v1.1.99@2017-03-20.适用的客户端版本5.2.6.1

  • 修正旧版本的KK客户端(v1.1.34@2016-09-20,适用的客户端版本5.2.5) 使用 kk.kkcontact.choose 报错的问题, 因为旧版KK返回的数据无 deptPath 导致。

v1.1.98@2017-03-07.适用的客户端版本5.2.6.1

  • 修正 kk.utils.isURL 判断问题,所有以 https? 打头的才判定为URL
  • 所有要判断URL的地方,均使用 kk.utils.isURL 判断,包括 file.view, media.save2album, share.to, app.callApp
  • kk.app.getClientInfo 增加 semver 字段,返回客户端的语义化版本号

v1.1.94@2017-02-28.适用的客户端版本5.2.6.1

  • 增加 kk.utils.isURL, 可用于判断参数是否为URL
  • 修改 kk.app.callApp, 支持在新窗口打开URL,打开的URL支持客户端的各种能力(代理请求,上传下载需要传入code). 同时修正 kk.app.callApp 实现不严谨的问题。

v1.1.93@2017-02-28.适用的客户端版本5.2.6

  • 增加 kk.app.onUpdate,可用该函数实现用户打开应用新版本时执行回调的功能
  • 修正 iOS 上由于 kk.ready 过快,导致调用 App.getClientConfig(此时app模块未定义) 获取 KK_WEBSERVER_HTTP_URL 报错的的问题

v1.1.89@2017-01-10.适用的客户端版本5.2.6

  • kk.app.getClientInfo 中加入企业相关信息
  • 修复kk.file.view不传成功回调时出错的bug
  • 更改kk.utils.extend实现方式,当dest为非对象时,不会报错

v1.1.85@2016-12-13.适用的客户端版本5.2.6

  • 移动kk.isOfflineApp至kk.app.isOfflineApp
  • 修复旧File模块view方法不传配置时会导致没有路径的bug

v1.1.84@2016-12-12.适用的客户端版本5.2.6

  • 扩展kk.share.to方法,使之更通用,目前该方法有三个原型
  • 扫描模块扫描二维码方法改名为scanQRCode,原方法名scanTDCode仍兼容

v1.1.80@2016-12-7.适用的客户端版本5.2.6

  • 修复因修改file模块的info方法名字而导致的旧方法调用出错的Bug
  • fixReadyArgs: 修复当通过callApp传复杂对象至app时,客户端无法解析复杂对象的bug
  • 修改share模块代码,将toWeixin与toKK结合成to方法
  • 删除kk.menu.share方法,该方法可使用kk.share.to('weixin', ...)实现

v1.1.77@2016-12-5.适用的客户端版本5.2.6

  • 修改原有file模块,使之能以kk.file.方法名的方式调用,原来的调用方式也兼容
  • 修复获取客户端web服务地址失败的bug
  • 修改share模块代码

v1.1.68@2016-12-2.适用的客户端版本5.2.6

  • kk.app.getUserInfo 修改实现方式,但功能不变。
  • kk.app.getAppInfo 增加查询应用信息
  • kk.app.getClientInfo 增加查询客户端信息
  • kk.app.getAppIcon(appCode) 增加根据app代码查询应用图标功能
  • 在kk.ready中获取kk服务的url
  • kk.econtact.getUserAvatar(loginName, isById) 根据登录名或ID查询用户头像
  • kk.econtact.getUserInfo 统一原有的kk.app.getUserInfo和kk.econtact.getUserInfoById
  • 新增share模块,用于分享消息至微信,或分享消息至KK,如kk.share.toWeixin和kk.share.appMessage

v1.1.55@2016-11-9.适用的客户端版本5.2.6

  • kk.app.getDeviceInfo 增加设备物理唯一ID。

v1.1.54@2016-11-8,适用的客户端版本5.2.6

  • 增加 deferred 模块,可为模块增加 promise 写法, 并暴露出为 kk.Deferred
  • kk.proxy.request 使用 deferred 重写,支持类 $.ajax 的写法。如 kk.proxy.request(...).done(...).fail(...).always(...)

v1.1.52@2016-11-1,适用的客户端版本5.2.6

  • kk.media.save2album 能力,客户端新增fileURI参数,支持保存在线图片到相册。
  • 修改 kk.media.save2album, 兼容、简化,用户只需输入uri就能调用能力。

v1.1.50@2016-10-26,适用的客户端版本5.2.5

  • 新增 Pay 支付模块
  • 新增 kk.pay.weixin 微信App支付能力

v1.1.34@2016-09-20,适用的客户端版本5.2.5

  • 去除 kk.econtact.getUserDepartById
  • 在kk.econtact.choose、kk.econtact.getUserInfoById 返回的结果新增 deptPath 字段,得到查询人员所在的所有部门

v1.1.33@2016-08-29,适用的客户端版本 5.2.5

  • 新增 kk.econtact.getUserDepartById 获取员工所在所有部门

v1.1.32@2016-08-03,适用的客户端版本 5.2.4

  • 将 kk.app.showMenuItems 及 kk.app.hideMenuItems 从app插件移动到 kk.menu
  • 新增 kk.menu.share 分享能力

v1.1.31@2016-08-01,适用的客户端版本 5.2.4

  • 新增 kk.app.showMenuItems 及 kk.app.hideMenuItems 能力,当前只默认支持全显示/全隐藏

v1.1.29@2016-07-13,适用的客户端版本 5.2.4

  • 在 kk.media.getPicture 能力新增imageTime和imageTimeString两个字段

v1.1.27@2016-07-12,适用的客户端版本 5.2.4

  • 修正 wasWrapper.exec 中的控制台调试
  • 新增 kk.media.getSignImage 获取签名图片的能力

v1.1.20@2016-05-31,适用的客户端版本 5.2.4

  • 修正 wasWrapper.exec 拼写错误导致native能力未准备好时调用能力JS SDK直接报错的问题

v1.1.19@2016-05-25,适用的客户端版本 5.2.4

  • 新增 kk.device.setClipboard 设置系统剪片版
  • 新增 kk.contact.choose 从系统通讯录选人
  • 修正 kk.contact.find 成功回调接受的参数为数组,之前为 对象

v1.1.11@2015-10-21

  • 新增 kk.media.previewImage 使用原生UI预览图片的能力

v1.1.10@2015-10-16

  • 新增 kk.app.setTitle 设置native导航栏标题的能力