微信小程序开发四：接口

4.1 网络

发起请求
wx.request接口，用于发起 HTTPS 请求。一个微信小程序，同时只能有5个网络请求连接。
上传下载
wx.uploadFile接口，用于将本地资源上传到开发者服务器。如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器。客户端发起一个 HTTPS POST 请求，其中 content-type 为 multipart/form-data 。
wx.downloadFile接口，用于下载文件资源到本地。客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径。
WebSocket
wx.connectSocket接口，用于创建一个 WebSocket 连接；一个微信小程序同时只能有一个 WebSocket 连接，如果当前已存在一个 WebSocket 连接，会自动关闭该连接，并重新创建一个 WebSocket 连接。
wx.onSocketOpen(CALLBACK)接口，用于监听WebSocket连接打开事件。
wx.onSocketError(CALLBACK)接口，用于监听WebSocket错误。
wx.sendSocketMessage(OBJECT)接口，用于通过 WebSocket 连接发送数据，需要先 wx.connectSocket，并在 wx.onSocketOpen 回调之后才能发送。
wx.onSocketMessage(CALLBACK)接口，用于监听WebSocket接受到服务器的消息事件。
wx.closeSocket()接口，用于关闭WebSocket连接。
wx.onSocketClose(CALLBACK)接口，用于监听WebSocket关闭。

4.2 媒体

图片
wx.chooseImage接口，用于从本地相册选择图片或使用相机拍照。wx.chooseImage的参数如表21-10所示。
wx.previewImage接口，用于预览图片。
wx.getImageInfo接口，用于获取图片信息。
音频
wx.startRecord接口，用于开始录音。当主动调用wx.stopRecord，或者录音超过1分钟时自动结束录音，返回录音文件的临时文件路径。
wx.stopRecord()接口，用于主动调用停止录音。
音频播放控制。
wx.playVoice接口，用于开始播放语音，同时只允许一个语音文件正在播放，如果前一个语音文件还没播放完，将中断前一个语音播放。
wx.pauseVoice接口，用于暂停正在播放的语音。再次调用wx.playVoice播放同一个文件时，会从暂停处开始播放。如果想从头开始播放，需要先调用 wx.stopVoice。
wx.stopVoice接口，用于结束播放语音。
wx.createAudioContext(audioId)接口，用于创建并返回 audio 上下文 audioContext 对象。
音乐播放控制
wx.getBackgroundAudioPlayerState接口，用于获取音乐播放状态。
wx.playBackgroundAudio接口，用于播放音乐，同时只能有一首音乐正在播放。
wx.pauseBackgroundAudio()接口，用于暂停播放音乐。
wx.seekBackgroundAudio接口，用于控制音乐播放进度。
wx.stopBackgroundAudio接口，用于停止播放音乐。
wx.onBackgroundAudioPlay接口，用于监听音乐播放。
wx.onBackgroundAudioPause接口，用于监听音乐暂停。
wx.onBackgroundAudioStop接口，用于监听音乐停止。
文件
wx.getSavedFileList接口，用于获取本地已保存的文件列表
wx.getSavedFileInfo接口，用于获取本地文件的文件信息
wx.removeSavedFile接口，用于删除本地存储的文件
视频
wx.chooseVideo接口，用于拍摄视频或从手机相册中选视频，返回视频的临时文件路径。
wx.createVideoContext接口，用于创建并返回 video 上下文 videoContext 对象
wx.chooseVideo的示例代码如下所示。

4.3 数据

每个微信小程序都可以有自己的本地缓存，可以通过 wx.setStorage（wx.setStorageSync）、wx.getStorage（wx.getStorageSync）、wx.clearStorage（wx.clearStorageSync）可以对本地缓存进行设置、获取和清理。本地缓存最大为10MB。需要注意的是localStorage 是永久存储的，但是不建议将关键信息全部存在 localStorage，以防用户换设备的情况。
wx.setStorage接口，用于将数据存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个异步接口。
wx.setStorageSync(KEY,DATA)接口，用于将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。
wx.getStorage接口，用于从本地缓存中异步获取指定 key 对应的内容。
wx.getStorageSync(KEY)接口，用于从本地缓存中同步获取指定 key 对应的内容。
wx.getStorageInfo(OBJECT)接口，用于异步获取当前storage的相关信息
wx.getStorageInfoSync接口，用于同步获取当前storage的相关信息
wx.removeStorage(OBJECT)接口，用于从本地缓存中异步移除指定 key 。
wx.removeStorageSync(KEY)接口，用于从本地缓存中同步移除指定 key 。
wx.clearStorage()接口，用于清理本地数据缓存。
wx.clearStorageSync()接口，用于同步清理本地数据缓存

4.4 位置

wx.getLocation(OBJECT)接口，用于获取当前的地理位置、速度。
wx.chooseLocation(OBJECT)接口，用于打开地图选择位置
wx.openLocation(OBJECT)接口，用于使用微信内置地图查看位置

4.5 设备

wx.getNetworkType(OBJECT)接口，用于获取网络类型。
wx.getSystemInfo(OBJECT)接口，用于获取系统信息。
wx.getSystemInfoSync()接口，用于获取系统信息同步接口
wx.onAccelerometerChange(CALLBACK)接口，用于监听重力感应数据，频率：5次/秒
wx.onCompassChange(CALLBACK)接口，用于监听罗盘数据，频率：5次/秒
wx.makePhoneCall(OBJECT)接口，用于拨打电话

4.6 界面

交互反馈
wx.showToast(OBJECT)接口，用于显示消息提示框
wx.showToast(OBJECT)接口，用于显示消息提示框
wx.hideToast()接口，用于隐藏消息提示框
wx.showModal(OBJECT)接口，用于显示模态弹窗
wx.showActionSheet(OBJECT)接口，用于显示操作菜单
设置导航条
wx.setNavigationBarTitle(OBJECT)接口，用于动态设置当前页面的标题。
wx.showNavigationBarLoading()接口，用于在当前页面显示导航条加载动画。
wx.hideNavigationBarLoading()接口，用于隐藏导航条加载动画。
wx.navigateTo(OBJECT)接口，用于保留当前页面，跳转到应用内的某个页面，使用wx.navigateBack可以返回到原页面。
wx.redirectTo(OBJECT)接口，用于关闭当前页面，跳转到应用内的某个页面。
wx.navigateBack(OBJECT)接口，用于关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages()) 获取当前的页面栈，决定需要返回几层。
动画
wx.createAnimation(OBJECT)接口，用于创建一个动画实例animation。调用实例的方法来描述动画。最后通过动画实例的export方法导出动画数据传递给组件的animation属性。
绘画
wx.createContext()接口，用于创建并返回绘图上下文context对象。
wx.drawCanvas(OBJECT)接口，用于描述画布。
wx.canvasToTempFilePath(OBJECT)接口，用于把当前画布的内容导出生成图片，并返回文件路径
其他
wx.hideKeyboard()接口，用于收起键盘。

4.7开放接口

登录
wx.login(OBJECT)接口，用于调用接口获取登录凭证（code）进而换取用户登录态信息，包括用户的唯一标识（openid）及本次登录的会话密钥（session_key）。用户数据的加解密通讯需要依赖会话密钥完成。登录部分代码如下所示。

//app.js
App({
  onLaunch: function() {
    wx.login({
      success: function(res) {
        if (res.code) {
          //发起网络请求
          wx.request({
            url: 'https://test.com/onLogin',
            data: {
              code: res.code
            }
          })
        } else {
          console.log('获取用户登录态失败！' + res.errMsg)
        }
      }
    });
  }
})

用户允许登录后，回调内容会带上 code（有效期五分钟），返回内容如下所示。
{errMsg: "login:ok", code: "013IwEe106FprD1A3Wd10HCGe10IwEeb"}
开发者需要将 code 发送到开发者服务器后台，使用code 换取 session_key接口，将 code 换成 openid 和 session_key。其中 session_key 是对用户数据进行加密签名的密钥。为了自身应用安全，session_key 不应该在网络上传输。code 换取 session_key接口如下
https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code
上述接口的参数说明如表21-32所示：

表21-32code 换取 session_key接口参数说明
正确创建时，返回的数据示例如下。

{
    "openid":"OPENID",
    "session_key":"SESSIONKEY",
    "expires_in":2592000
}

上述数据的参数说明如表21-33所示：

表21-33code换取session_key接口返回参数说明
通过 wx.login() 获取到用户登录态之后，需要维护登录态。要注意不应该直接把 session_key、openid 等字段作为用户的标识或者 session 的标识，而应该自己派发一个 session 登录态。对于开发者自己生成的 session，应该保证其安全性且不应该设置较长的过期时间。session 派发到小程序客户端之后，可将其存储在 storage ，用于后续通信使用。
用户信息
wx.getUserInfo(OBJECT)接口，用于获取用户信息。获取成功后，返回的内容参数如表21-34所示。

表21-34用户信息接口返回参数说明
获取用户信息的代码如下所示。

wx.getUserInfo({
  success: function(res) {
    var userInfo = res.userInfo
    var nickName = userInfo.nickName
    var avatarUrl = userInfo.avatarUrl
    var gender = userInfo.gender //性别 0：未知、1：男、2：女 
    var province = userInfo.province
    var city = userInfo.city
    var country = userInfo.country
  }
})

微信支付
wx.requestPayment(OBJECT)接口，用于发起微信支付。其参数如表21-35所示。

表21-35微信支付接口参数说明
发起微信支付的代码如下所示。

wx.requestPayment({
   'timeStamp': '',
   'nonceStr': '',
   'package': '',
   'signType': 'MD5',
   'paySign': '',
   'success':function(res){
   },
   'fail':function(res){
   }
})

模板消息
使用模板消息需要预先获取 access_token，获取方法可参考本书第五章。
发送模板消息的接口如下所示。
https://api.weixin.qq.com/cgi-bin/message/wxopen/template/send?access_token=ACCESS_TOKEN
POST数据时，提交的数据示例如下。

{
  "touser": "OPENID",  
  "template_id": "TEMPLATE_ID", 
  "page": "index",          
  "form_id": "FORMID",         
  "data": {
      "keyword1": {
          "value": "339208499", 
          "color": "#173177"
      }, 
      "keyword2": {
          "value": "2015年01月05日 12:30", 
          "color": "#173177"
      }, 
      "keyword3": {
          "value": "粤海喜来登酒店", 
          "color": "#173177"
      } , 
      "keyword4": {
          "value": "广州市天河区天河路208号", 
          "color": "#173177"
      } 
  },
  "emphasis_keyword": "keyword1.DATA" 
}

上述接口的参数说明如表21-36所示：

表21-36模板消息接口参数说明
正确创建时，返回的数据示例如下。

{"errcode":0,"errmsg":"ok"}