JSSDK 参考手册
优质
小牛编辑
142浏览
2023-12-01
开始
【通用说明】
微哨JSSDK是基于微哨内置浏览器进行扩展的一组JavaScript API，运行在微哨内置浏览器的web应用可以通过这些扩展API获得访问移动设备上的文件，摄像头，图片库以及扫描二维码等能力。
所有接口通过Whistle对象来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：
success：接口调用成功时执行的回调函数。
fail：接口调用失败时执行的回调函数。
complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。
cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。
注意：以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：
调用成功时：”xxx:ok” ，其中xxx为调用的接口名
用户取消时：”xxx:cancel”，其中xxx为调用的接口名
调用失败时：其值为具体错误信息
【环境要求】
目前微哨仅支持android和iOS两个平台，因此微哨的JSSDK仅能在android和iOS的微哨内置浏览器中运行。
注意：在android和iOS平台的自带浏览器中也不能运行
【步骤一】
请下载Whistle.js,并在页面中引入
示例：
<script> type="text/javascript" src="js/whistle-5.9.7.js" charset="utf-8" </>【步骤二】
微哨的扩展API只有在整个页面加载完毕有才有效，在页面没有加载完成前使用扩展API，可能不会有任何效果。
当微哨的扩展API准备完毕后，微哨将会回调Whistle.onReady = function(){…}
您的应用程序负责实现该回调函数。
【步骤三】
Whistle.onError=function(){…}
基础接口
【获取Whistle对象】
页面一旦引入微哨JSSDK后，Whistle对象将自动创建，所有的扩展API都将通过这个对象进行调用.
Whistle.sys对象主要用于区分当前的运行环境:
Whistle.sys.osName == Whistle.sys.ANDROID如果为true，表示当前页面运行在android平台
Whistle.sys.osName == Whistle.sys.IOS如果为true，表示当前页面运行在iOS平台
Whistle.sys.osName == Whistle.sys.OTHER如果为true，表示当页面前运行在微哨不支持的平台
设备相关接口
【Whistle.checkJsApi检测Api是否可用】
通过该api,可以检测客户端是否支持指定的Api
Whistle.checkJsApi({
jsApiList: ['setOrientation'], // 需要检测的JS接口列表，所有JS接口列表见附录2,
success: function(res) {
// 以键值对的形式返回，可用的api值true，不可用为false
// 如：{"checkResult":{"setOrientation":true},"errMsg":"checkJsApi:ok"}
}
});【Whistle.getNetworkType获取当前网络类型】
通过该api,可以获取当前微哨客户端所使用的网络类型以及网络的ipv4地址.
Whistle.getNetworkType({
success: function (res) {
var networkType = res.networkType; // 返回网络类型2g，3g，4g，wifi,unknown(未知,可能由于当前设备没有联网)
if(res.netaddress){
var ip = res.netaddress; // 返回对应的网络ip地址,如果无法获取地址,则为undefined.
}
if(res.ssid){
var ssid = res.ssid; // 返回对应的wifi网络接入的ssid名字,如果不是wifi,则为undefined.
}
if(res.bssid){//客户端5.9.3增加字段
var bssid = res.bssid; // 返回对应的wifi网络接入的bssid名字,如果不是wifi,则为undefined.
}
}
});【Whistle.getDeviceId获取设备唯一id】
通过该api,可以获取当前设备的唯一标识
Whistle.getDeviceId({
success: function (res) {
var deviceId = res.deviceId; // 返回设备的唯一标识符
}
});地理位置相关接口
【Whistle.getLocation获取当前地理位置】
通过该api,可以获取当前设备的地理位置信息
Whistle.getLocation({
success: function (res) {
var latitude = res.latitude; // 纬度，浮点数，范围为90 ~ -90
var longitude = res.longitude; // 经度，浮点数，范围为180 ~ -180。
var speed = res.speed; // 速度，以米/每秒计
var accuracy = res.accuracy; // 位置精度
}
});二维码相关接口
【Whistle.scanQRCode扫一扫】
通过该接口可以获得扫描条形码和二维码的能力.
Whistle.scanQRCode({
needResult:0,//默认为0，扫描结果由微哨处理，1则直接返回扫描结果
scanType:["qrCode","barCode"],//可以指定扫二维码还是一维码，默认是两者都有
success:function(res){
var result = res.resultStr;//当needResult为1时，可以通过这种方式获得扫码结果
}
});【Whistle.startScan扫码枪】
通过该接口可以获得连续扫描条形码和二维码的能力（5.9.3增加）
Whistle.startScan({
needResult:0, //默认为0，微哨处理后返回扫码后解出的userInfo
// 1则直接返回扫描原始结果
scanType：["qrCode","barCode"],
success: function (res) {
//当回调到此方法时,说明扫码枪启动成功，扫描结果通过Whistle.onScanCallback回调
},
fail:function (result) {
var errMsg = result.errMsg;
}
});【Whistle.onScanCallback扫码枪回调】
通过该接口可以注册扫码结果回调方法（5.9.3增加）
Whistle.onScanCallback({
success: function (res) {
//回调函数
res:{
"data":{
"name":"",
"nick_name":"",
"uid":"",
"student_number":"",
"sex":"",
"identity":"",
"photo":"",
"org":"",
"org_id":"",
"mood_words":"",
"schoolcode":""
}
}
}
});图片相关接口
【Whistle.previewImage预览图片】
通过Whistle.chooseImage拍照或从相册取图片.
Whistle.previewImage({
current:"http://c.hiphotos.baidu.com/image/pic/item/b3b7d0a20cf431ad018ee9f34236acaf2fdd9898.jpg",//选择3张图片
urls:['http://a.hiphotos.baidu.com/image/pic/item/a686c9177f3e670909f483ec31c79f3df8dc5529.jpg','http://a.app.qq.com/o/image/microQr.png?pkgName=cn.edu.dlut.ws','http://c.hiphotos.baidu.com/image/pic/item/b3b7d0a20cf431ad018ee9f34236acaf2fdd9898.jpg'],
});【Whistle.chooseImage拍照或从相册取图片】
通过Whistle.chooseImage拍照或从相册取图片.
Whistle.chooseImage({
count: 1, // 默认9
sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
success: function (res) {
var localIds = res.localIds; // 返回选定照片的本地ID列表，
$("#image").src = localIds[0];//localId可以作为img标签的src属性显示图片
},
cancel:function(res){
$('#chooseimage_case1').text('用户取消!');
}
});【Whistle.uploadImage上传图片】
通过Whistle.uploadImage上传图片.
Whistle.uploadImage({
localId: '', // 需要上传的图片的本地ID，由chooseImage接口获得
isShowProgressTips: 1, // 默认为1，显示进度提示
success: function (res) {
var imageUrl = res.imageUrl; // 返回图片上传后的访问url
}
});注意：目前该接口不支持同时调用多次来上传多个图片,程序逻辑必须等待一张图片完成后再上传下一张
【Whistle.downloadImage下载图片】
通过Whistle.downloadImage下载图片.
Whistle.downloadImage({
imageUrl: '', // 需要下载的图片的地址，由uploadImage接口获得
isShowProgressTips: 1, // 默认为1，显示进度提示
success: function (res) {
var localId = res.localId; // 返回图片下载后的本地ID
}
});计步器相关接口
【Whistle.startPedometer启动计步器】
通过该接口可以启动计步器
Whistle.startPedometer({
success:function(){
//当回调到此方法时,说明计步器启动成功
},
fail:function(result){
$("#startPedometer_result").text(result.errMsg);
}
});【Whistle.stopPedometer关闭计步器】
通过该接口可以关闭计步器
Whistle.stopPedometer({
success:function(){
//当回调到此方法时,说明计步器关闭成功
},
fail:function(result){
$("#stopPedometer_result").text(result.errMsg);
}
});【Whistle.getPedometerStatus查询计步器状态】
通过该接口可以查询计步器状态和最近7天步数
Whistle.getPedometerStatus({
success:function(res){
var status = res.status; //true为启动,false为关闭
var steps = res.steps; //最近7天步数值, steps[0]为当天的步数,steps[1]为昨天的步数,依次类推
}
});蓝牙beacon相关接口
【Whistle.startSearchBeacons启动蓝牙beacon扫描】
通过该接口可以启动蓝牙扫描beacon
Whistle.startSearchBeacons({
myBeacons: ['ec8764aa8a9248cd87dd28a942ec53e1', 'db76b82316d54da0b7f630a543f7800c', '64d4d9f25d17429fb22e4910e192cdb0'], //由于iOS对beacon扫描的限制,需要在此传入你要扫描的beacon的uuid, uuid中不包含'-',android不受此限制
success:function(){
//当回调到此方法时,说明蓝牙beacon扫描启动成功,开始执行扫描
},
fail:function(result){
$("#startSearchBeacons_result").text(result.errMsg);
}
});【Whistle.stopSearchBeacons停止蓝牙beacon扫描】
通过该接口可以停止蓝牙beacon扫描
Whistle.stopSearchBeacons({
success:function(){
//当回调到此方法时,说明蓝牙beacon扫描关闭
},
fail:function(result){
$("#stopSearchBeacons_result").text(result.errMsg);
}
});【Whistle.onSearchBeacons持续获取beacon扫描数据】
通过该接口可以注册beacon扫描回调，持续获取beacon扫描数据
Whistle.onSearchBeacons({
complete:function(argv){
//回调函数
/*
argv:{
"beacons":[
{
"major":10008,
"minor":57686,
"uuid":"FDA50693-A4E2-4FB1-AFCF-C6EB07647825",
"accuracy":"0.235344",
"rssi":"-66",
"proximity":"1",
"heading":"288.1355"
},
{
"major":10008,
"minor":57687,
"uuid":"FDA50693-A4E2-4FB1-AFCF-C6EB07647825",
"accuracy":"0.349124",
"rssi":"-49",
"proximity":"2",
"heading":"288.1355"
}
]
}
*/
}
});Wifi热点相关接口
【Whistle.getWifiScanList获取Wifi列表】
通过该接口可以获取扫描到的wifi列表
Whistle.getWifiScanList({
success: function (res) {
var wifiList = res.wifiList; // 返回扫描到的wifi信息数组
var wifiInfo = wifiList[0];
if(wifiInfo){
var ssid = wifiInfo.ssid; // 网络接入的ssid名字.
var bssid = wifiInfo.bssid // 网络接入的bssid名字.
var type = res.type; //返回网络安全加密类型 例如 open、wpa-psk等
}
},
fail:function (result) {
var errMsg = result.errMsg; //显示扫描失败的原因
}
});【Whistle.openWifiHotspot开启手机热点】
通过该接口可以开启个人手机热点
Whistle.openWifiHotspot({
ssid:'my_wifi', //热点的ssid iOS系统设置无效
password:'12345678', //热点的密码，iOS系统设置无效
type:'wpa2-psk', //热点安全认证类型，包含：open、wpa-psk、wpa2-psk，默认为wpa2-psk
success: function (res) { //当回调此方法时，说明热点开启成功。
var ssid = res.ssid; //返回热点的ssid
var ip = res.netaddress; //返回热点的ip地址
var type = res.type; //返回网络安全加密类型 例如 open、wpa-psk等
var bssid = res.bssid; //返回热点的bssid,android系统专用参数
},
fail:function (result) {
var errMsg = result.errMsg;
}
});【Whistle.closeWifiHotspot关闭手机热点】
通过该接口可以关闭手机热点
Whistle.closeWifiHotspot({
openWifi:true, //手机热点关闭后，是否需要开启wifi，默认为true，android专用参数
success: function (res) { //当回调此方法时，说明热点关闭成功。
var wifiStatus = res.wifiStatus; //wifi状态
},
fail:function (result) {
var errMsg = result.errMsg;
}
});【Whistle.getHotspotInfo获取个人热点信息】
通过该接口可以获取个人热点信息
Whistle.getHotspotInfo({
success: function (res) {
var status = res.status; //当前手机热点状态, true为开启, false为关闭
if(status) {
var ssid = res.ssid; //返回热点的ssid
var ip = res.netaddress; //返回热点的ip地址
var bssid = res.bssid; //返回热点的bssid,android系统专用参数
}
},
fail:function (result) {
var errMsg = result.errMsg;
}
});分享接口
【Whistle.onMenuShareTimeline分享内容到朋友圈】
通过该接口可以把对应的信息分享到微信朋友圈
Whistle.onMenuShareTimeline({
title: '', // 分享标题
link: '', // 分享链接
imgUrl: '', // 分享图标
//支持分享text，image，link三种类型，根据所传参数决定：
//只有title则为text类型；
//只有imgUrl则为image类型；
//title，link，imgUrl都有，则为link类型
success: function () {
// 用户点击了分享后执行的回调函数
}
});【Whistle.onMenuShareWechat分享内容到微信朋友】
通过该接口可以把对应的信息分享给微信好友
Whistle.onMenuShareWechat({
title: '', // 分享标题
desc: '', // 分享描述
link: '', // 分享链接
imgUrl: '', // 分享图标
type: '', //
//分享类型支持text，image，link，music，video（music和video需要指定，其他类型可不传）
//text：只传desc
//image：只传imgUrl
//link：需传title，desc，link，imgUrl（imgUrl不传则图片显示为微哨logo）
//music & video：通过type指定类型，需要所有参数
dataUrl: '', // 如果type是music或video，则要提供数据链接，默认为空
success: function () {
// 用户点击了分享后执行的回调函数
}
});【Whistle.onMenuShareQQ分享内容到QQ朋友】
通过该接口可以把对应的信息分享给QQ好友
Whistle.onMenuShareQQ({
title: '', // 分享标题
desc: '', // 分享描述
link: '', // 分享链接
imgUrl: '', // 分享图标
musicUrl: '',//分享音乐
success: function () {
// 用户确认分享后执行的回调函数
},
cancel: function () {
// 用户取消分享后执行的回调函数
}
});其他接口
【Whistle.httpRequestData发送网络请求】
该接口可以通过微哨客户端发起http请求，可以用来解决JS跨域请求的问题
Whistle.httpRequestData({
methodName: 'GET', // 暂时仅支持 GET 和 POST, 默认为GET
requestUrl: '', // 请求目标的url，支持HTTPS, 默认是http协议
requestParams: {'key':'value'}, // 发起请求包含的参数，Json格式。
headers: {'key':'value'}, // 发起请求的头，Json格式，如果为空则使用默认的头，包含Accept-Language和UA。
success: function (result) {
var data = result.responseData; // 返回选定照片的本地ID列表
}，
fail:function(result){
var errMsg = result.errMsg;//错误信息
var errCode = result.errCode;//错误码
}
});【Whistle.startNativePage 启动本地界面】
通过该接口可以启动微哨客户端里的页面，暂时只支持启动校园卡，通讯录，个人资料，聊天
Whistle.startNativePage({
pageName:"", // 目前只支持schoolCard(校园卡), contacts（通讯录）, myInfo（个人资料）, chat（聊天）其他值直接回调fail（）
data:{}, //启动页面需要传的参数，目前仅chat需要传参 data:{uid:"10001"}
success: function (res) {
//回调此方法表示启动native界面成功
},
fail:function (result) {
var errMsg = result.errMsg;
}
});【Whistle.notifyUser提示用户】
通过该接口能够以播放提示音、震动、弹toast的方式给用户反馈
Whistle.notifyUser({
playSound:true, // 播放提示音
vibrate:true, // 手机震动
toast:"接口调用成功", // toast提示
success:function (res) {
//回调此方法表示启动native界面成功
}
});