微信JS-SDK的使用
微信JS-SDK是微信公众平台面向网页开发者提供的基于微信内的网页开发工具包。
通过使用微信JS-SDK，网页开发者可借助微信高效地使用拍照、选图、语音、位置等手机系统的能力，同时可以直接使用微信分享、扫一扫、卡券、支付等微信特有的能力，为微信用户提供更优质的网页体验。
1. 微信JS-SDK使用步骤
1.1. 绑定域名；
登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”。在设置安全域名时，根据注意事项的提示，将下载的文件上传到服务器的根目录下。
注意：如果需要支付功能，还要配置以下两项：
1. “公众号设置”－“功能设置”，配置网页授权域名；
2. “商户平台”－“产品中心”－“开发配置”，配置公众号支付授权目录。目录必须为支付页面的上一级页面地址；
如：http://www.xiaoduanfa.com/pay/index.html，填写的目录为 http://www.xiaoduanfa.com/pay/
1.2. 配置IP白名单；
在微信公众平台左侧选择“基本配置”，然后打开IP白名单，填写IP地址。
1.3. 引入JS文件；
在需要调用JS接口的页面引入如下JS文件:http://res.wx.qq.com/open/js/jweixin-1.2.0.js。
备注：支持使用 AMD/CMD 标准模块加载方法加载。
1.4. 通过config接口注入权限验证配置；
所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用。
wx.config({
// 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
debug: true,
// 必填，公众号的唯一标识
appId: '',
// 必填，生成签名的时间戳
timestamp: ,
// 必填，生成签名的随机串
nonceStr: '',
// 必填，签名
signature: '',
// 必填，需要使用的JS接口列表
jsApiList: []
});由于签名获取比较麻烦，官方文档 介绍的也比较烦锁， 以下简单介绍一下获取步骤：
1. 通过你的微信号里的 APPID 和 APPSECRET 得到 access_token，请求方式如下：
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
2. 根据 access_token 获取 ticket，请求方式如下：
https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi
3. 根据ticket获取签名；
在以上地址中填写jsapi_ticket、noncestr、timestamp和url，生成签名。
1.5. 引入JS-SDK成功后的回调函数，所有的JS-SDK方法都放到这个里面；
wx.ready(function(){
// config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});1.6. 引入JS-SDK失败后的回调函数；
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中的相关接口；
备注：不要尝试在trigger中使用ajax异步请求修改本次分享的内容，因为客户端分享操作是一个同步操作，这时候使用ajax的回调还没有返回。
以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：
调用成功时："xxx:ok" ，其中xxx为调用的接口名。
用户取消时："xxx:cancel"，其中xxx为调用的接口名。
调用失败时：其值为具体错误信息。
2. 常见接口的使用
2.1. 基础接口；
1. 判断当前客户端版本是否支持指定JS接口；
wx.checkJsApi({
// 需要检测的JS接口列表
jsApiList: ['chooseImage'],
// 成功后的回调
success: function(res) {
// 以键值对的形式返回，可用的api值true，不可用为false
// 如：{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
}
});备注：checkJsApi接口是客户端6.0.2新引入的一个预留接口，第一期开放的接口均可不使用checkJsApi来检测。
2.2. 分享接口；
请注意不要有诱导分享等违规行为，对于诱导分享行为将永久回收公众号接口权限，详细规则请查看：朋友圈管理常见问题 。
1. 获取“分享到朋友圈”按钮点击状态及自定义分享内容接口；
wx.onMenuShareTimeline({
// 分享标题
title: '',
// 分享链接，该链接域名或路径必须与当前页面对应的公众号JS安全域名一致
link: '',
// 分享图标
imgUrl: '',
// 用户确认分享后执行的回调函数
success: function () {
},
// 用户取消分享后执行的回调函数
cancel: function () {
}
});2. 获取“分享给朋友”按钮点击状态及自定义分享内容接口；
wx.onMenuShareAppMessage({
// 分享标题
title: '',
// 分享描述
desc: '',
// 分享链接，该链接域名或路径必须与当前页面对应的公众号JS安全域名一致
link: '',
// 分享图标
imgUrl: '',
// 分享类型,music、video或link，不填默认为link
type: '',
// 如果type是music或video，则要提供数据链接，默认为空
dataUrl: '',
// 用户确认分享后执行的回调函数
success: function () {
},
// 用户取消分享后执行的回调函数
cancel: function () {
}
});3. 获取“分享到QQ”按钮点击状态及自定义分享内容接口；
wx.onMenuShareQQ({
// 分享标题
title: '',
// 分享描述
desc: '',
// 分享链接
link: '',
// 分享图标
imgUrl: '',
// 用户确认分享后执行的回调函数
success: function () {
},
// 用户取消分享后执行的回调函数
cancel: function () {
}
});4. 获取“分享到腾讯微博”按钮点击状态及自定义分享内容接口；
wx.onMenuShareWeibo({
// 分享标题
title: '',
// 分享描述
desc: '',
// 分享链接
link: '',
// 分享图标
imgUrl: '',
// 用户确认分享后执行的回调函数
success: function () {
},
// 用户取消分享后执行的回调函数
cancel: function () {
}
});5. 获取“分享到QQ空间”按钮点击状态及自定义分享内容接口；
wx.onMenuShareQZone({
// 分享标题
title: '',
// 分享描述
desc: '',
// 分享链接
link: '',
// 分享图标
imgUrl: '',
// 用户确认分享后执行的回调函数
success: function () {
},
// 用户取消分享后执行的回调函数
cancel: function () {
}
});
2.3. 图像接口；
1. 拍照或从手机相册中选图接口；
wx.chooseImage({
// 默认9
count: 1,
// 可以指定是原图还是压缩图，默认二者都有
sizeType: ['original', 'compressed'],
// 可以指定来源是相册还是相机，默认二者都有
sourceType: ['album', 'camera'],
success: function (res) {
// 返回选定照片的本地ID列表，localId可以作为img标签的src属性显示图片
var localIds = res.localIds;
}
});2. 预览图片接口；
wx.previewImage({
// 当前显示图片的http链接
current: '',
// 需要预览的图片http链接列表
urls: []
});3. 上传图片接口；
wx.uploadImage({
// 需要上传的图片的本地ID，由chooseImage接口获得
localId: '',
// 默认为1，显示进度提示
isShowProgressTips: 1,
success: function (res) {
// 返回图片的服务器端ID
var serverId = res.serverId;
}
});备注：上传图片有效期3天，可用微信多媒体接口下载图片到自己的服务器，此处获得的 serverId 即 media_id。
4. 下载图片接口；
wx.downloadImage({
// 需要下载的图片的服务器端ID，由uploadImage接口获得
serverId: '',
// 默认为1，显示进度提示
isShowProgressTips: 1,
success: function (res) {
// 返回图片下载后的本地ID
var localId = res.localId;
}
});
5. 获取本地图片接口；
wx.getLocalImgData({
// 图片的localID
localId: '',
success: function (res) {
// localData是图片的base64数据，可以用img标签显示
var localData = res.localData;
}
});
备注：此接口仅在 iOS WKWebview 下提供，用于兼容 iOS WKWebview 不支持 localId 直接显示图片的问题。具体可参考《iOS网页开发适配指南》
2.4. 音频接口；
1. 开始录音接口；
wx.startRecord();2. 停止录音接口；
wx.stopRecord({
success: function (res) {
var localId = res.localId;
}
});3. 监听录音自动停止接口；
wx.onVoiceRecordEnd({
// 录音时间超过一分钟没有停止的时候会执行 complete 回调
complete: function (res) {
var localId = res.localId;
}
});4. 播放语音接口；
wx.playVoice({
// 需要播放的音频的本地ID，由stopRecord接口获得
localId: ''
});5. 暂停播放接口；
wx.pauseVoice({
// 需要暂停的音频的本地ID，由stopRecord接口获得
localId: ''
});6. 停止播放接口；
wx.stopVoice({
// 需要停止的音频的本地ID，由stopRecord接口获得
localId: ''
});7. 监听语音播放完毕接口；
wx.onVoicePlayEnd({
success: function (res) {
// 返回音频的本地ID
var localId = res.localId;
}
});8. 上传语音接口；
wx.uploadVoice({
// 需要上传的音频的本地ID，由stopRecord接口获得
localId: '',
// 默认为1，显示进度提示
isShowProgressTips: 1,
success: function (res) {
// 返回音频的服务器端ID
var serverId = res.serverId;
}
});
备注：上传语音有效期3天，可用微信多媒体接口下载语音到自己的服务器，此处获得的 serverId 即 media_id，参考文档 .目前多媒体文件下载接口的频率限制为10000次/天，如需要调高频率，请登录微信公众平台，在开发 - 接口权限的列表中，申请提高临时上限.
9. 下载语音接口；
wx.downloadVoice({
// 需要下载的音频的服务器端ID，由uploadVoice接口获得
serverId: '',
// 默认为1，显示进度提示
isShowProgressTips: 1,
success: function (res) {
// 返回音频的本地ID
var localId = res.localId;
}
});2.5. 智能接口；
1. 识别音频并返回识别结果接口；
wx.translateVoice({
// 需要识别的音频的本地Id，由录音相关接口获得
localId: '',
// 默认为1，显示进度提示
isShowProgressTips: 1,
success: function (res) {
// 语音识别的结果
alert(res.translateResult);
}
});2.6. 设备信息；
1. 获取网络状态接口；
wx.getNetworkType({
success: function (res) {
// 返回网络类型2g，3g，4g，wifi
var networkType = res.networkType;
}
});2.7. 地理位置；
1. 使用微信内置地图查看位置接口；
wx.openLocation({
// 纬度，浮点数，范围为90 ~ -90
latitude: 0,
// 经度，浮点数，范围为180 ~ -180。
longitude: 0,
// 位置名
name: '',
// 地址详情说明
address: '',
// 地图缩放级别,整形值,范围从1~28。默认为最大
scale: 1,
// 在查看位置界面底部显示的超链接,可点击跳转
infoUrl: ''
});2. 获取地理位置接口；
wx.getLocation({
// 默认为wgs84的gps坐标，如果要返回直接给openLocation用的火星坐标，可传入'gcj02'
type: 'wgs84',
success: function (res) {
// 纬度，浮点数，范围为90 ~ -90
var latitude = res.latitude;
// 经度，浮点数，范围为180 ~ -180。
var longitude = res.longitude;
// 速度，以米/每秒计
var speed = res.speed;
// 位置精度
var accuracy = res.accuracy;
}
});2.8. 摇一摇周边；
1. 开启查找周边ibeacon设备接口；
wx.startSearchBeacons({
//摇周边的业务ticket, 系统自动添加在摇出来的页面链接后面
ticket:"",
//开启查找完成后的回调函数
complete:function(argv){
}
});备注：如需接入摇一摇周边功能，请参考：申请开通摇一摇周边
2. 关闭查找周边ibeacon设备接口；
wx.stopSearchBeacons({
complete:function(res){
//关闭查找完成后的回调函数
}
});3. 监听周边ibeacon设备接口；
wx.onSearchBeacons({
//回调函数，可以数组形式取得该商家注册的在周边的相关设备列表
complete:function(argv){
}
});备注：上述摇一摇周边接口使用注意事项及更多返回结果说明，请参考：摇一摇周边获取设备信息
2.9. 界面操作；
1. 关闭当前网页窗口接口；
wx.closeWindow();2. 批量隐藏功能按钮接口；
wx.hideMenuItems({
// 要隐藏的菜单项，只能隐藏“传播类”和“保护类”按钮
menuList: []
});3. 批量显示功能按钮接口；
wx.showMenuItems({
// 要显示的菜单项
menuList: []
});4. 隐藏所有非基础按钮接口；
wx.hideAllNonBaseMenuItem();5. 显示所有功能按钮接口；
wx.showAllNonBaseMenuItem();2.10. 微信扫一扫；
1. 调起微信扫一扫接口；
wx.scanQRCode({
// 默认为0，扫描结果由微信处理，1则直接返回扫描结果，
needResult: 0,
// 可以指定扫二维码还是一维码，默认二者都有
scanType: ["qrCode","barCode"],
success: function (res) {
// 当needResult 为 1 时，扫码返回的结果
var result = res.resultStr;
}
});2.11. 微信小店；
1. 跳转微信商品页接口；
wx.openProductSpecificView({
// 商品id
productId: '',
// 0.默认值，普通商品详情页1.扫一扫商品详情页2.小店商品详情页
viewType: ''
});2.12. 微信卡券；
微信卡券接口中使用的签名凭证api_ticket，与步骤三中config使用的签名凭证jsapi_ticket不同，开发者在调用微信卡券JS-SDK的过程中需依次完成两次不同的签名，并确保凭证的缓存。
获取api_ticket：api_ticket 是用于调用微信卡券JS API的临时票据，有效期为7200 秒，通过access_token 来获取。
开发注意事项：
A. 用于卡券接口签名的api_ticket与步骤三中通过config接口注入权限验证配置使用的jsapi_ticket不同；
B. 由于获取api_ticket 的api 调用次数非常有限，频繁刷新api_ticket 会导致api调用受限，影响自身业务，开发者需在自己的服务存储与更新api_ticket；
接口调用请求说明
http请求方式: GET
https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card
//access_token:接口调用凭证返回数据示例:
{
"errcode":0,
"errmsg":"ok",
"ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA",
"expires_in":7200
}1. 拉取适用卡券列表并获取用户选择信息；
wx.chooseCard({
// 门店Id
shopId: '',
// 卡券类型
cardType: '',
// 卡券Id
cardId: '',
// 卡券签名时间戳
timestamp: 0,
// 卡券签名随机串
nonceStr: '',
// 签名方式，默认'SHA1'
signType: '',
// 卡券签名
cardSign: '',
success: function (res) {
// 用户选中的卡券列表信息
var cardList= res.cardList;
}
});特别提醒：
A. 签名错误会导致拉取卡券列表异常为空，请仔细检查参与签名的参数有效性；
B. 拉取列表仅与用户本地卡券有关，拉起列表异常为空的情况通常有三种：签名错误、时间戳无效、筛选机制有误,，请开发者依次排查定位原因；
2. 批量添加卡券接口；
wx.addCard({
// 需要添加的卡券列表
cardList: [{
cardId: '',
cardExt: ''
}],
success: function (res) {
// 添加的卡券列表信息
var cardList = res.cardList;
}
});3. 查看微信卡包中的卡券接口；
wx.openCard({
// 需要打开的卡券列表
cardList: [{
cardId: '',
code: ''
}]
});2.13. 微信支付；
wx.chooseWXPay({
// 支付签名时间戳，注意微信jssdk中的所有使用timestamp字段均为小写。但最新版的支付后台生成签名使用的timeStamp字段名需大写其中的S字符
timestamp: 0,
// 支付签名随机串，不长于 32 位
nonceStr: '',
// 统一支付接口返回的prepay_id参数值，提交格式如：prepay_id=***）
package: '',
// 签名方式，默认为'SHA1'，使用新版支付需传入'MD5'
signType: '',
// 支付签名
paySign: '',
// 支付成功后的回调函数
success: function (res) {
}
});备注：prepay_id 通过微信支付统一下单接口拿到，paySign 采用统一的微信支付 Sign 签名生成方法，注意这里 appId 也要参与签名，appId 与 config 中传入的 appId 一致，即最后参与签名的参数有appId, timeStamp, nonceStr, package, signType。
微信支付开发文档：https://pay.weixin.qq.com/wiki/doc/api/index.html
2.14. 快速输入；
1. 共享收货地址接口；
wx.openAddress({
success: function (res) {
// 收货人姓名
var userName = res.userName;
// 邮编
var postalCode = res.postalCode;
// 国标收货地址第一级地址（省）
var provinceName = res.provinceName;
// 国标收货地址第二级地址（市）
var cityName = res.cityName;
// 国标收货地址第三级地址（国家）
var countryName = res.countryName;
// 详细收货地址信息
var detailInfo = res.detailInfo;
// 收货地址国家码
var nationalCode = res.nationalCode;
// 收货人手机号码
var telNumber = res.telNumber;
}
});