小程序文档整理之 -- API（网络请求）

网络

发起请求

wx.request(object)

wx.request({
  url: 'test.php', //（必须）接口地址，不能有端口
  data: { //传入参数
     x: '' ,
     y: ''
  },
  header: {//设置请求的 header,把传入的参数转化成string
      'content-type': 'application/json'//（默认）转化成JSON
      'content-type': 'application/x-www-form-urlencoded'//转化成 query string 
  },
  method: GET,//请求方式 OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT（需大写）
  dataType:'json'//如果设为json，将返回的数据转化为JSON
  success: function(res) {//接口调用成功的回调函数
    res.data;//返回的数据
    res.header;//返回的 HTTP Response Header
    res.statusCode;//返回的 HTTP 状态码
  },
  fail: function(res){//接口调用失败的回调函数
  },
  complete: function(res){//接口调用结束的回调函数(成功、失败都会执行）
  },
})
requestTask.abort() // 取消请求任务

上传下载

wx.uploadFile(object)上传文件

将本地资源上传到开发者服务器，客户端发起一个 HTTPS POST 请求，其中 content-type 为 multipart/form-data

wx.chooseImage({
  success: function(res) {
    var tempFilePaths = res.tempFilePaths
    const uploadTask = wx.uploadFile({
      url: 'https://example.weixin.qq.com/upload', //（必填）接口地址
      filePath: tempFilePaths[0],//（必填）要上传文件资源的路径
      name: 'file',//（必填）文件对应的 key
      header: {//设置请求的 header,把传入的参数转化成string
          'content-type': 'application/json'//（默认）转化成JSON
          'content-type': 'application/x-www-form-urlencoded'//转化成 query string 
      },
      formData:{//HTTP 请求中其他额外的 form data
        'user': 'test'
      },
      success: function(res) {//接口调用成功的回调函数
        res.data;//返回的数据
        res.statusCode;//返回的 HTTP 状态码
      },
      fail: function(res){//接口调用失败的回调函数
      },
      complete: function(res){//接口调用结束的回调函数(成功、失败都会执行）
      }
    })
    uploadTask.onProgressUpdate((res) => {
        res.progress;//上传进度
        res.totalBytesSent;//已经上传的数据长度
        res.totalBytesExpectedToSend;//预期需要上传的数据总长度
    })
    uploadTask.abort() // 取消上传任务
  }
})

wx.downloadFile(object)

下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径

const downloadTask = wx.downloadFile({
    url: 'http://example.com/audio/123', //资源下载地址
    header: {//设置请求的 header,把传入的参数转化成string
          'content-type': 'application/json'//（默认）转化成JSON
          'content-type': 'application/x-www-form-urlencoded'//转化成 query string 
    },
    success: function(res) {//接口调用成功的回调函数，下载成功后以 tempFilePath 的形式传给页面，res = {tempFilePath: '文件的临时路径'}，文件的临时路径，在小程序本次启动期间可以正常使用，如需持久保存，需在主动调用 wx.saveFile，在小程序下次启动时才能访问得到。
        res.data;//返回的数据
        res.statusCode;//返回的 HTTP 状态码
    },
    fail: function(res){//接口调用失败的回调函数
    },
    complete: function(res){//接口调用结束的回调函数(成功、失败都会执行）
    }
});
//监听下载进度变化
downloadTask.onProgressUpdate((res) => {
    res.progress;//上传进度
    res.totalBytesSent;//已经上传的数据长度
    res.totalBytesExpectedToSend;//预期需要上传的数据总长度
});
// 取消下载任务
downloadTask.abort();

WebSocket

wx.connectSocket(object)

创建一个 WebSocket 连接

wx.connectSocket({
  url: 'test.php',
  data:{
    x: '',
    y: ''
  },
  header:{ 
    'content-type': 'application/json'
  },
  method:"GET",//请求方式 OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT（需大写）
  protocols: ['protocol1'],
  success: function(res) {//接口调用成功的回调函数
  },
  fail: function(res){//接口调用失败的回调函数
  },
  complete: function(res){//接口调用结束的回调函数(成功、失败都会执行）
  },
})

wx.onSocketOpen(callback)

监听WebSocket连接打开事件

wx.onSocketOpen(function(res) {
  console.log('WebSocket连接已打开！')
})

wx.onSocketError(callback)

监听WebSocket错误

wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res){
  console.log('WebSocket连接已打开！')
})
wx.onSocketError(function(res){
  console.log('WebSocket连接打开失败，请检查！')
})

wx.sendSocketMessage(object)

通过 WebSocket 连接发送数据，需要先 wx.connectSocket，并在 wx.onSocketOpen 回调之后才能发送

var socketOpen = false
var socketMsgQueue = []
//创建一个 WebSocket 连接
wx.connectSocket({
  url: 'test.php'
})
//监听WebSocket连接打开事件
wx.onSocketOpen(function(res) {
  socketOpen = true
  for (var i = 0; i < socketMsgQueue.length; i++){
     sendSocketMessage(socketMsgQueue[i])
  }
  socketMsgQueue = []
})

function sendSocketMessage(msg) {
  if (socketOpen) {
  //通过 WebSocket 连接发送数据
    wx.sendSocketMessage({
      data:msg,//（必填）需要发送的内容
      success: function(res) {//接口调用成功的回调函数
      },
      fail: function(res){//接口调用失败的回调函数
      },
      complete: function(res){//接口调用结束的回调函数(成功、失败都会执行）
      },
    })
  } else {
     socketMsgQueue.push(msg)
  }
}

wx.onSocketMessage(callback)

监听WebSocket接受到服务器的消息事件

wx.connectSocket({
  url: 'test.php'
})

wx.onSocketMessage(function(res) {
  res.data;//服务器返回的消息
})

wx.closeSocket(object)

关闭WebSocket连接

wx.connectSocket({
  url: 'test.php'
})
//关闭WebSocket连接
wx.closeSocket(function(res) {
  code,//一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是1000 （表示正常连接关闭）
  reason,//一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本（不是字符）
  success: function(res) {//接口调用成功的回调函数
  },
  fail: function(res){//接口调用失败的回调函数
  },
  complete: function(res){//接口调用结束的回调函数(成功、失败都会执行）
  },
})

wx.onSocketClose(callback)

监听WebSocket关闭

wx.connectSocket({
  url: 'test.php'
})
//注意这里有时序问题，
//如果 wx.connectSocket 还没回调 wx.onSocketOpen，而先调用 wx.closeSocket，那么就做不到关闭 WebSocket 的目的。
//必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。
wx.onSocketOpen(function() {
  wx.closeSocket()
})
//监听WebSocket关闭
wx.onSocketClose(function(res) {
  console.log('WebSocket 已关闭！')
})