云之家JS-API文档

特别说明： 桌面端从UserAgent版本0.0.2开始支持部分JS-API接口！所支持的接口为：

1、概述

云之家JS-API能够提供轻应用在云之家中更好的展示和交互，方便轻应用轻松获得云之家的设备能力。

1.1、使用必要条件

轻应用必须应用于云之家APP(注意的是：目前云之家移动端可以使用全部的JS-API接口、桌面端仅有部分接口使用)中，如果脱离了云之家APP，而在其他的浏览器中打开，则不能使用到云之家的JS-API功能。

使用Javascript进行调用！

桌面端从userAgent版本0.0.2开始支持部分JS-API接口，同时支持桌面端的JS-API接口会有(桌面端+)的标识。依然通过qing.js来调用，有些细节不一致的将在下面说明

1.2、JS-API介绍

1.3、JS-API使用步骤

1.3.1、引入JS文件

在需要调用JS接口的页面引入如下JS文件，qingjs.js

引入示例：

1.3.2、调用处理

笔者建议在对云之家JS-API接口进行调用前，先判断当前环境是否支持调用JS-API接口，以便在不同环境中调用时有一些辅助的提示信息。

以“获取当前用户身份信息”的JS-API接口为例，示例代码：

//判断是否运行于云之家App中

function isYzjApp () {

return navigator.userAgent.match(/Qing\/.*;(iPhone|Android).*/)?true:false;

}

/* 判断是否运行于云之家桌面端

* @return {object} cloudhub 返回是否桌面端、当前桌面端userAgent版本及是否支持JS-API

* cloudhub = {isCloudHub: true | false, hasJS-APIt: true | false, version: '0.0.1'}

*/

function getCloudHub () {

var ua = window.navigator.userAgent;

var reg = /cloudhub 10204\/([^;]+)/;

var cloudhub = {

isCloudHub: false,

hasJS-APIt: false,

version: ''

};

var match = reg.exec(ua), version;

if (match) {

version = match[1];

cloudhub.isCloudHub = true,

cloudhub.version = version;

if (version.replace(/\./g, '') > 1) {

cloudhub.hasJS-APIt = true;

}

}

return cloudhub;

}

//获取操作系统平台，

iOS或Android

function getOS () {

return (navigator.userAgent.match(/\(i[^;]+;( U;)? CPU.+Mac OS X/) ? 'iOS' :

navigator.userAgent.match(/Android/i) ? 'Android' : '' );

}

// 是否在手机上

function isMobile () {

var os = getOS();

return os == 'iOS' || os == 'Android';

}

if (!isYzjApp() || !getCloudHub().isCloudHub) {

$body.html("Hello！当前不在云之家App(桌面端)中！开启您的轻应用之旅吧！");

if(!isMobile()) {

$body.html("Hello！当前不在手机端上！开启您的轻应用之旅吧！");

}

} else {

XuntongJSBridge.call('getPersonInfo', {}, function(result) {

if (null != result && undefined != result) {

/* **** 注意 start **** */

/* **** 由于在桌面端，实现JS-API方式不同，这里的回调返回值result是一个string **** */

/* **** 为确保result正常使用，建议在回调中添加如下代码 **** */

if (typeof result == 'string') {

result = JSON.parse(result);

}

/* **** 注意 end **** */

var desc = "返回的数据:

var success = String(result.success);

if (success == "true") {

$body.html(desc + "。

} else if (success == "false") {

$body.html(desc + "。

} else {

$body.html("返回有问题！");

}

} else {

$body.html("返回失败！");

}

});

}

1.3.3、处理回调

当调用云之家JS-API后，当返回为空时，表明处理成功，轻应用可以自行处理后续的工作；当有返回时，轻应用对此返回结果进行处理后再进行后续的开发，返回的格式为：

{

success: true or false 是否成功(string)

error: 错误信息(string)

errorCode: 错误码(int)

data: {

...

}

}

其中的返回说明如下表。

字段名称数据类型说明

successstring接口调用是否成功。返回“true”说明成功；返回“false”说明失败；返回“其他的”说明接口实现有问题。

errorstring接口调用失败的详细信息。

errorCodeint接口调用失败的错误码。

datajson接口调用成功，返回的数据。

特别注意：由于历史实现问题，Android返回的success字段返回类型为boolean，而iOS返回类型为字符串，即Android的success的值为true/false；iOS的success的值为"true"/"false"。为综合这两种情况，可以采取如下代码解决问题：var success = String(result.success);

if (success == "true") {

...

} else if (success == "false") {

...

} else {

alert("接口返回值非法！");

}

** 桌面端调用JS-API可根据返回值的errorCode来判断是否支持该JS-API(仅桌面端可用) ，若 errorCode == 404，表示桌面端不支持该JS-API

2、基础接口

由于目前桌面端JS-API版本的差异，以及仅支持部分接口，所以基础接口在这里的逻辑并没有给出对应方法，如需应用在云之家桌面端展示的，请参照下”调用处理”中相应代码。

2.1、判断当前客户端的身份

识别用户当前所处环境为非手机端还是Android还是iOS。见如下代码：

//获取操作系统平台，iOS或Android

function getOS () {

return (navigator.userAgent.match(/\(i[^;]+;( U;)? CPU.+Mac OS X/) ? 'iOS' :

navigator.userAgent.match(/Android/i) ? 'Android' : '' );

}

当以上方法返回不为Android或iOS时，则说明用户当前所处环境为非手机端。

2.2、判断当前环境是否支持JS-API

(1). 判断思路：判断当前环境是否支持JS-API，该依据是通过云之家轻应用专属的UserAgent值来判断。

云之家App轻应用的UserAgent格式如下：

轻应用框架标示/轻应用框架版本;系统名称 系统版本;手机品牌;手机硬件型号

例如：

iOS：Qing/0.9.0;iPhone OS 9.1;Apple;iPhone7,1 (iPhone7,1表示该机器为iPhone 6 Plus，参考iPhone Models)

Android：Qing/0.9.0;Android4.1.1;Xiaomi;MI 2

总结：

云之家App轻应用的UserAgent是以“/Qing\/.*;(iPhone|Android).*/”该正则表达式来匹配，当匹配到这个时，即云之家的客户端。

特别注意：

开发者不能直接单纯地拿以上的举例去作识别。即不能以如下代码：

navigator.userAgent == "Qing/0.9.0;iPhone OS 9.1;Apple;iPhone7,1 " ||

navigator.userAgent == "Qing/0.9.0;Android4.1.1;Xiaomi;MI 2 "

这样去判断，因为轻应用框架的版本号及其他的项并不是一成不变的！

当轻应用URL必须经过第三方服务进行转换时，第三方服务必须将来自于云之家的UserAgent进行转发，以免轻应用中获取到错误的运行环境，造成轻应用布局或业务不能达到预期的目标。

(2). 可以通过如下代码，进行判断：

// 轻应用是否运行于云之家的框架中而非其他浏览器中

navigator.userAgent.match(/Qing\/.*;(iPhone|Android).*/)?true:false;

当以上代码返回true，即当前环境支持JS-API，也即轻应用运行于云之家的框架中而非其他浏览器中。

3、隐藏或者设置页面标题

XuntongJSBridge.call('hideWebViewTitle');//隐藏页面标题

XuntongJSBridge.call('setWebViewTitle',{'title':'申请加入群聊'});//设置页面标题并显示

参数说明：

参数名称数据类型必选说明

titlestring是需要设置的标题

回调说明：无

4、获取当前用户身份信息(桌面端+)

仅限获取姓名、性别、头像、企业ID和用户ID。更多信息可参考获取云之家app当前用户上下文。

XuntongJSBridge.call('getPersonInfo', {}, function(result){

alert("用户数据："+JSON.stringify(result));

});

参数说明：无

回调说明：

{

success: true or false 是否成功(string)

error: 错误信息(String)

errorCode: 错误码(int)

data: {

name:用户姓名(string)

photoUrl:用户头像地址(string)

gender:用户性别(int)

eid:云之家账号体系下的工作圈id(string)

openId:云之家账号体系下的用户id(string)

wbuserid:部落账号体系下的用户id(string)

wbnetworkid:部落账号体系下的工作圈id(string)

}

}

data中字段说明：

字段名称数据类型说明

namestring用户姓名。

photoUrlstring用户头像地址。

genderint用户性别，”0”为”男”,”1”为”女”。

eidstring云之家账号体系下的工作圈id。

openIdstring云之家账号体系下的用户id。

wbuseridstring部落账号体系下的用户id。

wbnetworkidstring部落账号体系下的工作圈id。

5、获取用户网络状态

XuntongJSBridge.call('getNetworkType', {}, function(result){

alert("用户网络状态："+JSON.stringify(result));

});

参数说明：无

回调说明：

{

success: true or false 是否成功(string)

error: 错误信息(String)

errorCode: 错误码(int)

data: {

network_type:网络类型(string)

}

}

data中字段说明：

字段名称数据类型说明

network_typestring网络类型。

6、打开第三方应用

XuntongJSBridge.call('gotoApp', {

"data":'yunzhijia://p?url=https://itunes.apple.com/cn/app/id595672427'

}, function(result) {

alert("结果："+JSON.stringify(result));

});

参数说明：

参数名称数据类型必选说明

datastring是第三方应用跳转Scheme。

其中url是必须的，表示应用的下载地址。

如果手机未安装应用，则跳转至此地址进行安装；

如果还需其他参数，则使用 & 接到后面；

如果是Android，也可定义为：packageName://className?key=value&key=value；

回调说明：

当调用成功时直接打开了第三方应用。

当调用失败时：

{

success: false

error: 错误信息(String)

errorCode: 错误码(int)

data:

}

7、进入会话

XuntongJSBridge.call('chat', {

'openId':'ge6sjw12sda2scdfefe2'

}, function(result) {

alert("结果："+JSON.stringify(result));

});

参数说明：

参数名称数据类型必选说明

openIdstring与groupId二选一云之家账号体系下对话人的用户ID。

groupIdstring与openId二选一会话组ID。

回调说明：

{

success: true or false 是否成功(string)

error: 错误信息(String)

errorCode: 错误码(int)

data:

}

8、唤起人员详情页面

这里说的人员详情是指调出云之家APP上面的人员详情页，而不是返回人员详细的内容。

XuntongJSBridge.call('personInfo', {

'openId':'ge6sjw12sda2scdfefe2'

}, function(result) {

alert("结果："+JSON.stringify(result));

});

参数说明：

参数名称数据类型必选说明

openIdstring是云之家账号体系下的用户ID。

回调说明：

当调用成功时直接调出指定人的个人信息详情页。

当调用失败时：

{

success: false

error: 错误信息(String)

errorCode: 错误码(int)

data:

}

9、转发接口

轻应用转发信息给用户或聊天组(桌面端+)

XuntongJSBridge.call("share", {

"shareType":"4",

"appId":"XXX",

"appName":"XXX",

"lightAppId":"XXX",

"title":"XXX",

"content":"XXX",

"thumbData":"XXX",

"thumbUrl":"xxx",

"webpageUrl":"XXX",

"cellContent":"XXX",

"sharedObject":"XXX",

"callbackUrl":"XXX"

}, function(result) {

alert("结果："+JSON.stringify(result));

});

参数说明：

参数名称数据类型必选说明

shareTypestring是转发类型，目前仅支持4，表示轻应用转发信息。

appIdstring是轻应用ID或公共号ID，当为轻应用时传轻应用ID；当为公共号时传公共号ID。

appNamestring是轻应用名称或公共号名称，当为轻应用时传轻应用名称；当为公共号时传公共号名称。

themestring否主题(可选)，如传入，创建组时以此命名组名称。

lightAppIdstring否轻应用ID(如果需要获取ticket，则必须传入此参数)。

titlestring是新闻标题。

contentstring是新闻内容。

thumbDatastringthumbUrl与thumbData二选一新闻缩略图，使用Base64编码。

thumbUrlstringthumbUrl与thumbData二选一新闻缩略图，完整的图片url。

webpageUrlstring是新闻的url。

cellContentstring是在聊天界面显示的内容。

sharedObjectstring是转发的对象：all(所有)，group(组)，person(人)。

callbackUrlstring否回调url，可选。

如果不为空，客户端会先调用此url，并且传入以下参数：

groupId或personId、eId、openId、content

(另外如果是一呼百应，需要使用云之家的token和token secret对请求进行签名，

即OAuth)

此url处理完业务后需返回：

{

“data”:“id=3dsfj7322jfnbg20s3d2”,

“error”:null,

“errorCode”:0,

“success”:true

}

取到data中的数据后接到webpageUrl后面。

callbackParamobject({key: value})否*仅桌面端支持*，回调callbackUrl时需要传入的额外参数及参数值

回调说明：

{

success: true or false 是否成功(string)

error: 错误信息(String)

errorCode: 错误码(int)

data:

}

10、切换工作圈

XuntongJSBridge.call("switchCompany", {

"eid":"XXX"

}, function(result) {

alert("结果："+JSON.stringify(result));

});

参数说明：

参数名称数据类型必选说明

eidstring是云之家工作圈企业号。

回调说明：

{

success: true or false 是否成功(string)

error: 错误信息(String)

errorCode: 错误码(int)

data:

}

11、关闭轻应用界面

调用代码：

XuntongJSBridge.call('closeWebView');

参数说明：无

回调说明：无

12、获取图片

获取图片说的是调起云之家app的”获取图片”页，目前有2种方式:选择图片文件,或直接拍照。

调用代码：

XuntongJSBridge.call('selectPic', {'type':'camera'}, function(result){

alert("结果："+JSON.stringify(result));

});

参数说明：

参数名称数据类型必选说明

typestring否类型，“camera”代表“相机”，“photo”代表“相册”，不传表示从相机、相册中选择(Qing/0.9.10及以上支持。)

回调说明：

{

success: true or false 是否成功(string)

error: 错误信息(string)

errorCode: 错误码(int)

data: {

fileExt:文件后缀(string)

fileData:文件数据的base64字符串(string)

}

}

data中字段说明：

字段名称数据类型说明

fileExtstring文件后缀。

fileDatastring用户头像地址。

13、扫一扫

XuntongJSBridge.call("scanQRCode", {

"needResult":0

}, function(result) {

});

参数说明：

参数名称数据类型必选说明

needResultint否是否需要处理，默认为0，扫描结果由云之家处理，1则直接返回扫描结果。

回调说明：

{

success: true or false 是否成功(String)

error: 错误信息(String)

errorCode: 错误码(int)

data:{

"qrcode_str":"xxx"

}

}

data字段说明：

字段名称数据类型说明

qrcode_strstring扫码返回的结果，该结果在needResult为1的时候；当needResult为0时，data字段不返回。

14、自定义右上角弹出菜单

XuntongJSBridge.call('createPop',

{

'popTitle':String,

'popTitleCallBackId':String,

'items':[

{'text':String,'callBackId':'String'},

{'text':String,'callBackId':'String'},

...

],

'menuList' : ['forward'(转发),'refresh'(刷新),'share'(分享),'openWithBrowser'(在浏览器中打开)],

'shareData' : {

'isShowExt':'转发时是否显示商务伙伴，true or false，默认为true'

'title' : '分享或者转发的标题',

'url' : '分享的链接，若空则取当前的url',

'description' : '分享或者转发的内容',

'appLogo' : '轻应用Logo，base64数据'

'appName' : '轻应用名称'

}

},

function(result){}

);

参数说明：

参数名称数据类型必选说明

popTitlestring否右上角弹出菜单名称，只支持最多4位中文字符，超出部分会截断显示(不传入popTitle，如果最后传入的有效条 目数大于0，则会默认显示云之家”更多”图标，如果有效条目数为0，则右上角不显示任何内容)

popTitleCallBackIdstring是点击右上角回调ID

itemsarray(object{'text':String,'callBackId':'String'})否自定义菜单条目(text：菜单条目文本、callBackId：回调ID)

menuListarray(string)否系统菜单条目，目前支持share(分享)、refresh(刷新)、openWithBrowser(在浏览器中打开)、forward(转发)

shareDataobject否分享或者转发的内容

注：

1、自定义菜单条目items数量和系统菜单条目menuList数量加起来不超过7条，如超过则优先显示系统菜单条目(比如items数量为5，menuList数量为4，则显示items前3条加menuList里的4条)；

2、菜单显示顺序为优先显示自定义菜单条目，然后显示系统菜单条目，系统条目按JS方法传入的menuList顺序来显示；

15、关闭右上角弹出菜单

XuntongJSBridge.call('closePop');

16、云之家定位

XuntongJSBridge.call('getLocation');

回调说明：

{

success: true or false 是否成功(String)

error: 错误信息(String)

errorCode: 错误码(int)

data:{'latitude'：22.2748379, //维度

'longitude':133.2324334, //经度

'province':'广东省', //省

'city':'深圳市', //市

'district':'南山区', //区

'name':'金蝶软件园', //名称

'address':'科技南十二道', //地址

'addressdetail':广东省深圳市南山区科技南十二道' //详细地址

}

}

17、云之家选取周边位置

XuntongJSBridge.call('selectLocation', {

'latitude':22.394839,

'longitude':133.374833,

'isLocation':false

}, function(result){

});

参数说明：

参数名称数据类型必选说明

latitudedouble是获取周边位置的中心纬度。

longitudedouble是获取周边位置的中心经度。

isLocationint否是否自动定位然后获取周边。

回调说明：

{

success: true or false 是否成功(String)

error: 错误信息(String)

errorCode: 错误码(int)

data:{'latitude'：22.2748379, //维度

'longitude':133.2324334, //经度

'province':'广东省', //省

'city':'深圳市', //市

'district':'南山区', //区

'name':'金蝶软件园', //名称

'address':'科技南十二道', //地址

'addressdetail':广东省深圳市南山区科技南十二道' //详细地址

}

}

18、选择人员

XuntongJSBridge.call('selectPersons',

{'isMulti':false},

function(result){}

);

参数说明：

参数名称数据类型必选说明

isMultiint否是否为多选，默认false。

回调说明：

{

success: true or false 是否成功(String)

error: 错误信息(String)

errorCode: 错误码(int)

data:{persons:[{

name: 用户姓名

avatarUrl:用户图像地址

openId: 用户Id

},...]

}

}

19、查看文件详情

XuntongJSBridge.call('showFile',

{

'fileId':'hde22fdej233',

'fileName':'计划',

'fileExt':'ppt',

'fileTime':'2014-11-28 13:23:54',

'fileSize':35500

},

function(result){}

);

参数说明：

参数名称数据类型必选说明

fileIdstring否文件ID，第三方文件不传。

fileNamestring是文件名称

fileExtstring是文件后缀

fileTimestring是时间

fileSizeint是文件大小，单位：字节

fileDownloadUrlstring否文件下载地址，非云之家的第三方文件传入此参数，可直接下载并打开文件

回调说明：无

20、选择文件

XuntongJSBridge.call('selectFile',

{},

function(result){}

);

参数说明：无

回调说明：

{

success: true or false 是否成功(String)

error: 错误信息(String)

errorCode: 错误码(int)

data:{

files:[{

fileId: 文件Id，String

fileName: 文件名称，String

fileExt: 文件后缀，String

fileTime: 时间，String

fileSize: 文件大小，int，单位：字节

},...]

}

}

21、自定义返回按钮事件

XuntongJSBridge.call('defback',

{},

function () {

alert('点击了返回按钮');

if (history.length <= 1) { //顶级页面，则关闭当前Web

XuntongJSBridge.call('closeWebView');

} else {

history.back();

}

}

);

参数说明：无

回调说明：无

22、获取或者设置粘贴板内容

XuntongJSBridge.call('clipBoard',

{

'type':'getString or setString',

'string':'设置的内容'

},

function(result){}

);

参数说明：

参数名称数据类型必选说明

typestring是getString表示获取粘贴板内容，setString表示设置粘贴板内容

stringstring否getString时传空，setString时传入需要设置的内容

回调说明：

{

success: true or false 是否成功(String)

error: 错误信息(String)

errorCode: 错误码(int)

data:{

'string': '粘贴板内容' //getString才会返回此值

}

}

DEMO页面

更新日志

0.9.0

hideWebViewTitle

setWebViewTitle

gotoApp

getPersonInfo

getNetworkType

share

switchCompany

chat

selectFile

showFile

selectPic

scanQRCode

selectPersons

0.9.4

getPersonInfo(增加返回值companyName)

0.9.5

closeWebView

0.9.6

createPop

closePop

getLocation

selectLocation

0.9.11

defback

0.9.12

clipBoard

全名:

E-Mail:

请输入您的评论:

请在输入框中填入验证码以证明您不是机器人。 P E R KL 请将此区域留空：