微信JS SDK 接口调用详解.docx
《微信JS SDK 接口调用详解.docx》由会员分享，可在线阅读，更多相关《微信JS SDK 接口调用详解.docx（25页珍藏版）》请在冰豆网上搜索。
微信JSSDK接口调用详解
微信JSSDK调用详解
目录
∙1概述
o1.1使用说明
▪1.1.1步骤一：
引入JS文件
▪1.1.2步骤二：
通过config接口注入权限验证配置
▪1.1.3步骤三：
通过ready接口处理成功验证
▪1.1.4步骤四：
通过error接口处理失败验证
o1.2接口调用说明
∙2基础接口
o2.1判断当前客户端版本是否支持指定JS接口
∙3分享接口
o3.1获取“分享到朋友圈”按钮点击状态及自定义分享内容接口
o3.2获取“分享给朋友”按钮点击状态及自定义分享内容接口
o3.3获取“分享到QQ”按钮点击状态及自定义分享内容接口
o3.4获取“分享到腾讯微博”按钮点击状态及自定义分享内容接口
∙4图像接口
o4.1拍照或从手机相册中选图接口
o4.2预览图片接口
o4.3上传图片接口
o4.4下载图片接口
∙5音频接口
o5.1开始录音接口
o5.2停止录音接口
o5.3监听录音自动停止接口
o5.4播放语音接口
o5.5暂停播放接口
o5.6停止播放接口
o5.7监听语音播放完毕接口
o5.8上传语音接口
o5.9下载语音接口
∙6智能接口
o6.1识别音频并返回识别结果接口
∙7设备信息
o7.1获取网络状态接口
∙8地理位置
o8.1使用微信内置地图查看位置接口
o8.2获取地理位置接口
∙9界面操作
o9.1隐藏右上角菜单接口
o9.2显示右上角菜单接口
o9.3关闭当前网页窗口接口
o9.4批量隐藏功能按钮接口
o9.5批量显示功能按钮接口
o9.6隐藏所有非基础按钮接口
o9.7显示所有功能按钮接口
∙10微信扫一扫
o10.1调起微信扫一扫接口
∙11微信小店
o11.1跳转微信商品页接口
∙12微信卡券
o12.1调起适用于门店的卡券列表并获取用户选择列表
o12.2批量添加卡券接口
o12.3查看微信卡包中的卡券接口
∙13微信支付
o13.1发起一个微信支付请求
∙14附录1-JS-SDK使用权限签名算法
∙15附录2-所有JS接口列表
∙16附录3-所有菜单项列表
∙17附录4-位置签名生成算法
∙18附录5-支付扩展字段及签名生成算法
∙19附录6-卡券扩展字段及签名生成算法
∙20附录7-常见错误及解决方法
∙21附录8-DEMO页面和示例代码
∙22附录9-问题反馈
概述
微信JS-SDK是微信公众平台面向网页开发者提供的基于微信内的网页开发工具包。
通过使用微信JS-SDK，网页开发者可借助微信高效地使用拍照、选图、语音、位置等手机系统的能力，同时可以直接使用微信分享、扫一扫、卡券、支付等微信特有的能力，为微信用户提供更优质的网页体验。
此文档面向网页开发者介绍微信JS-SDK如何使用及相关注意事项。
使用说明
在使用微信JS-SDK对应的JS接口前，需确保公众号已获得使用对应JS接口的权限，可登录微信公众平台进入“开发者中心”查看对应的接口权限。
注意：
所有的JS接口只能在公众号绑定的域名下调用，公众号开发者需要先登录微信公众平台进入“公众号设置”》“功能设置”里填写“JS接口安全域名”。
步骤一：
引入JS文件
在需要调用JS接口的页面引入如下JS文件，（支持https）：
备注：
支持使用AMD/CMD标准模块加载方法加载
步骤二：
通过config接口注入权限验证配置
所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用（同一个url仅需调用一次，对于变化url的SPA的webapp可在每次url变化时进行调用）。
wx.config（{
debug:
true,//开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
appId:
'',//必填，公众号的唯一标识
timestamp:
//必填，生成签名的时间戳
nonceStr:
'',//必填，生成签名的随机串
signature:
'',//必填，签名，见附录1
jsApiList:
[]//必填，需要使用的JS接口列表，所有JS接口列表见附录2
}）;
步骤三：
通过ready接口处理成功验证
wx.ready（function（）{
//config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。
对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
}）;
步骤四：
通过error接口处理失败验证
wx.error（function（res）{
//config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
}）;
接口调用说明
所有接口通过wx对象（也可使用jWeixin对象）来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：
1.success：
接口调用成功时执行的回调函数。
2.fail：
接口调用失败时执行的回调函数。
3.complete：
接口调用完成时执行的回调函数，无论成功或失败都会执行。
4.cancel：
用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。
5.trigger:
监听Menu中的按钮点击时触发的方法，该方法仅支持Menu中的相关接口。
以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：
1.调用成功时：
"xxx:
ok"，其中xxx为调用的接口名
2.用户取消时：
"xxx:
cancel"，其中xxx为调用的接口名
3.调用失败时：
其值为具体错误信息
基础接口
判断当前客户端版本是否支持指定JS接口
wx.checkJsApi（{
jsApiList:
['chooseImage']//需要检测的JS接口列表，所有JS接口列表见附录2,
success:
function（res）{
//以键值对的形式返回，可用的api值true，不可用为false
//如：
{"checkResult":
{"chooseImage":
true},"errMsg":
"checkJsApi:
ok"}
}）;
备注：
checkJsApi接口是客户端6.0.2新引入的一个预留接口，第一期开放的接口均可不使用checkJsApi来检测。
分享接口
请注意不要有诱导分享等违规行为，对于诱导分享行为将永久回收公众号接口权限，详细规则请查看：
朋友圈管理常见问题 。
获取“分享到朋友圈”按钮点击状态及自定义分享内容接口
wx.onMenuShareTimeline（{
title:
'',//分享标题
link:
'',//分享链接
imgUrl:
'',//分享图标
success:
function（）{
//用户确认分享后执行的回调函数
},
cancel:
function（）{
//用户取消分享后执行的回调函数
}
}）;
获取“分享给朋友”按钮点击状态及自定义分享内容接口
wx.onMenuShareAppMessage（{
title:
'',//分享标题
desc:
'',//分享描述
link:
'',//分享链接
imgUrl:
'',//分享图标
type:
'',//分享类型,music、video或link，不填默认为link
dataUrl:
'',//如果type是music或video，则要提供数据链接，默认为空
success:
function（）{
//用户确认分享后执行的回调函数
},
cancel:
function（）{
//用户取消分享后执行的回调函数
}
}）;
获取“分享到QQ”按钮点击状态及自定义分享内容接口
wx.onMenuShareQQ（{
title:
'',//分享标题
desc:
'',//分享描述
link:
'',//分享链接
imgUrl:
''//分享图标
success:
function（）{
//用户确认分享后执行的回调函数
},
cancel:
function（）{
//用户取消分享后执行的回调函数
}
}）;
获取“分享到腾讯微博”按钮点击状态及自定义分享内容接口
wx.onMenuShareWeibo（{
title:
'',//分享标题
desc:
'',//分享描述
link:
'',//分享链接
imgUrl:
''//分享图标
success:
function（）{
//用户确认分享后执行的回调函数
},
cancel:
function（）{
//用户取消分享后执行的回调函数
}
}）;
图像接口
拍照或从手机相册中选图接口
wx.chooseImage（{
success:
function（res）{
varlocalIds=res.localIds;//返回选定照片的本地ID列表，localId可以作为img标签的src属性显示图片
}
}）;
预览图片接口
wx.previewImage（{
current:
'',//当前显示的图片链接
urls:
[]//需要预览的图片链接列表
}）;
上传图片接口
wx.uploadImage（{
localId:
'',//需要上传的图片的本地ID，由chooseImage接口获得
isShowProgressTips:
1//默认为1，显示进度提示
success:
function（res）{
varserverId=res.serverId;//返回图片的服务器端ID
}
}）;
备注：
可用微信下载多媒体文件接口下载上传的图片，此处获得的serverId即media_id，参考文档 ../12/58bfcfabbd501c7cd77c19bd9cfa8354.html
下载图片接口
wx.downloadImage（{
serverId:
'',//需要下载的图片的服务器端ID，由uploadImage接口获得
isShowProgressTips:
1//默认为1，显示进度提示
success:
function（res）{
varlocalId=res.localId;//返回图片下载后的本地ID
}
}）;
音频接口
开始录音接口
wx.startRecord（）;
停止录音接口
wx.stopRecord（{
success:
function（res）{
varlocalId=res.localId;
}
}）;
监听录音自动停止接口
wx.onVoiceRecordEnd（{
//录音时间超过一分钟没有停止的时候会执行complete回调
complete:
function（res）{
varlocalId=res.localId;
}
}）;
播放语音接口
wx.playVoice（{
localId:
''//需要播放的音频的本地ID，由stopRecord接口获得
}）;
暂停播放接口
wx.pauseVoice（{
localId:
''//需要暂停的音频的本地ID，由stopRecord接口获得
}）;
停止播放接口
wx.stopVoice（{
localId:
''//需要停止的音频的本地ID，由stopRecord接口获得
}）;
监听语音播放完毕接口
wx.onVoicePlayEnd（{
serverId:
'',//需要下载的音频的服务器端ID，由uploadVoice接口获得
success:
function（res）{
varlocalId=res.localId;//返回音频的本地ID
}
}）;
上传语音接口
wx.uploadVoice（{
localId:
'',//需要上传的音频的本地ID，由stopRecord接口获得
isShowProgressTips:
1//默认为1，显示进度提示
success:
function（res）{
varserverId=res.serverId;//返回音频的服务器端ID
}
}）;
备注：
可用微信下载多媒体文件接口下载上传的语音，此处获得的serverId即media_id，参考文档 ../12/58bfcfabbd501c7cd77c19bd9cfa8354.html
下载语音接口
wx.downloadVoice（{
serverId:
'',//需要下载的音频的服务器端ID，由uploadVoice接口获得
isShowProgressTips:
1//默认为1，显示进度提示
success:
function（res）{
varlocalId=res.localId;//返回音频的本地ID
}
}）;
智能接口
识别音频并返回识别结果接口
wx.translateVoice（{
localId:
'',//需要识别的音频的本地Id，由录音相关接口获得
isShowProgressTips:
1,//默认为1，显示进度提示
success:
function（res）{
alert（res.translateResult）;//语音识别的结果
}
}）;
设备信息
获取网络状态接口
wx.getNetworkType（{
success:
function（res）{
varnetworkType=workType;//返回网络类型2g，3g，4g，wifi
}
}）;
地理位置
使用微信内置地图查看位置接口
wx.openLocation（{
latitude:
0,//纬度，浮点数，范围为90~-90
longitude:
0,//经度，浮点数，范围为180~-180。
name:
'',//位置名
address:
'',//地址详情说明
scale:
1,//地图缩放级别,整形值,范围从1~28。
默认为最大
infoUrl:
''//在查看位置界面底部显示的超链接,可点击跳转
}）;
获取地理位置接口
wx.getLocation（{
timestamp:
0,//位置签名时间戳，仅当需要兼容6.0.2版本之前时提供
nonceStr:
'',//位置签名随机串，仅当需要兼容6.0.2版本之前时提供
addrSign:
'',//位置签名，仅当需要兼容6.0.2版本之前时提供，详见附录4
success:
function（res）{
varlongitude=res.longitude;//纬度，浮点数，范围为90~-90
varlatitude=res.latitude;//经度，浮点数，范围为180~-180。
varspeed=res.speed;//速度，以米/每秒计
varaccuracy=res.accuracy;//位置精度
}
}）;
界面操作
隐藏右上角菜单接口
wx.hideOptionMenu（）;
显示右上角菜单接口
wx.showOptionMenu（）;
关闭当前网页窗口接口
wx.closeWindow（）;
批量隐藏功能按钮接口
wx.hideMenuItems（{
menuList:
[]//要隐藏的菜单项，所有menu项见附录3
}）;
批量显示功能按钮接口
wx.showMenuItems（{
menuList:
[]//要显示的菜单项，所有menu项见附录3
}）;
隐藏所有非基础按钮接口
wx.hideAllNonBaseMenuItem（）;
显示所有功能按钮接口
wx.showAllNonBaseMenuItem（）;
微信扫一扫
调起微信扫一扫接口
wx.scanQRCode（{
desc:
'scanQRCodedesc',
needResult:
0,//默认为0，扫描结果由微信处理，1则直接返回扫描结果，
scanType:
["qrCode","barCode"],//可以指定扫二维码还是一维码，默认二者都有
success:
function（res）{
varresult=res.resultStr;//当needResult为1时，扫码返回的结果
}
}）;
微信小店
跳转微信商品页接口
wx.openProductSpecificView（{
productId:
'',//商品id
viewType:
''//0.默认值，普通商品详情页1.扫一扫商品详情页2.小店商品详情页
}）;
微信卡券
调起适用于门店的卡券列表并获取用户选择列表
wx.chooseCard（{
shopId:
'',//门店Id
cardType:
'',//卡券类型
cardId:
'',//卡券Id
timeStamp:
0,//卡券签名时间戳
nonceStr:
'',//卡券签名随机串
cardSign:
'',//卡券签名，详见附录6
success:
function（res）{
varcardList=res.cardList;//用户选中的卡券列表信息
}
}）;
批量添加卡券接口
wx.addCard（{
cardList:
[{
cardId:
'',
cardExt:
''
}],//需要添加的卡券列表
success:
function（res）{
varcardList=res.cardList;//添加的卡券列表信息
}
}）;
查看微信卡包中的卡券接口
wx.openCard（{
cardList:
[{
cardId:
'',
code:
''
}]//需要打开的卡券列表
}）;
微信支付
发起一个微信支付请求
wx.chooseWXPay（{
timestamp:
0,//支付签名时间戳
noncestr:
'',//支付签名随机串
package:
'',//订单详情扩展字符串，详见附录5
paySign:
'',//支付签名，详见附录5
}）;
附录1-JS-SDK使用权限签名算法
jsapi_ticket
生成签名之前必须先了解一下jsapi_ticket，jsapi_ticket是公众号用于调用微信JS接口的临时票据。
正常情况下，jsapi_ticket的有效期为7200秒，通过access_token来获取。
由于获取jsapi_ticket的api调用次数非常有限，频繁刷新jsapi_ticket会导致api调用受限，影响自身业务，开发者必须在自己的服务全局缓存jsapi_ticket 。
1.参考以下文档获取access_token（有效期7200秒，开发者必须在自己的服务全局缓存access_token）：
../15/54ce45d8d30b6bf6758f68d2e95bc627.html
2.用第一步拿到的access_token采用httpGET方式请求获得jsapi_ticket（有效期7200秒，开发者必须在自己的服务全局缓存jsapi_ticket）：
成功返回如下JSON：
{
"errcode":
0,
"errmsg":
"ok",
"ticket":
"bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",
"expires_in":
7200
}
获得jsapi_ticket之后，就可以生成JS-SDK权限验证的签名了。
签名算法
签名生成规则如下：
参与签名的字段包括noncestr（随机字符串）,有效的jsapi_ticket,timestamp（时间戳）,url（当前网页的URL，不包含#及其后面部分）。
对所有待签名参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1。
这里需要注意的是所有参数名均为小写字符。
对string1作sha1加密，字段名和字段值都采用原始值，不进行URL转义。
即signature=sha1（string1）。
示例：
∙noncestr=Wm3WZYTPz0wzccnW
∙jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg
∙timestamp=1414587457
∙url=
步骤1.对所有待签名参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1：
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW×tamp=1414587457&url=
步骤2.对string1进行sha1签名，得到signature：
f4d90daf4b3bca3078ab155816175ba34c443a7b
注意事项
1.签名用的noncestr和timestamp必须与wx
升级会员 