微信小程序学习之路——API网络

我们之前已经介绍了小程序组件的使用方法，运用这些组件我们就可以构建我们所需要的UI界面，但是小程序的一些功能需要依赖框架提供的API来完成。API包括了网络、媒体、文件、数据缓存、位置、设备、界面、开放接口8大类，这些API由微信本身提供，通过逻辑层JS代码进行调用。在介绍小程序API在定义和使用上一些通用规则。一般来说，微信API按命名规则可以分为两种：

• 以w.on开头的API，如：wx.onSocketOpen、wx.onBackgroundAudioPlay()、wx.on-Com-passChange()等，均代表监听某个事情发生的API接口，这类接口一般来说参数均为一个callback回调函数，当该事件触发时，会回调callback函数。
• 其他不以wx.on开头的API，如：wx.request、wx.uploadFile、wx.chooseImage，这类接口如果没有特殊约定，通常都接收一个Object对象作为参数，在Object中可以指定success、fail、compete来接收接口调用结果，这三个回调函数在某些API中具有返回值，有些没有

两种调用方式如下：

//以wx.on开头
wx.onSocketOpen(function(res){
    console.log('WebSocket链接已打开');
});
//不以wx.on开头
wx.request({
/*接口调用成功*/
success:function(){},
/*接口调用失败*/
fail:function(){},
/*接口调用结束（调用成功、失败都会执行）*/
complete:function(){}
})    

网络：

每个微信小程序需要实现设置一个通信域名，小程序可以跟指定的域名进行网络通信。包括不同的HTTPS请求(wx.request)、WebSocket通信(wx.connectSocket)、上传文件(wx.uploadFile)和下载文件(wx.downloadFile)。设置通信域名需要登陆小程序“后台->设置->开发设置，”在服务器配置中添加受新任的域。

发起HTTPS请求

wx.request(Object)

request用于发起HTTPS请求，默认超时时间和最大超时时间都是60秒。在小程序中只能使用HTTPS请求不能使用HTTP请求，一个微信小程序，同时只能有5个网络请求链接。Object参数属性如下：

属性	类型	默认值	必填	说明	最低版本
url	string		是	开发者服务器接口地址
data	string/object/ArrayBuffer		否	请求的参数
header	Object		否	设置请求的 header，header 中不能设置 Referer。 content-type 默认为 application/json
method	string	GET	否	HTTP 请求方法
dataType	string	json	否	返回的数据格式
responseType	string	text	否	响应的数据类型	1.7.0
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

 

data数据最终发送给服务器的数据是String类型，如果传入的data不是String类型，则会被转化成String，转换规则如下：

1. 对于header['content-type']为'application/json'的数据，会对数据进行JSON序列化
2. 对于header['content-type']为'application/x-www-form-urlencoded'的数据，会将数据转换成query string(encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)......)

示例代码如下：

wx.request({
    url:'https://www.dmail.com',
header:{
    'Content-Type':'application/json'
},
success:function(e){
    console.log(e);
},
complete:function(){
    console.log('无论成功失败都会执行')
}
});

上传、下载

wx.uploadFile(Object)

之前提到的request仅用于与服务端进行简单通讯，如果需要提交带本地资源的数据，便需要调用此接口将本地资源上传到指定服务器，调用这个uploadFile时，客户端会向服务端发起一个HTTP POST请求，header中Content-Type为multipart/form-data。上传文件最大并发限制为10个，默认超时时间和最大超时时间都是60秒，Object参数属性如下：

属性	类型	默认值	必填	说明
url	string		是	开发者服务器地址
filePath	string		是	要上传文件资源的路径
name	string		是	文件对应的 key，开发者在服务端可以通过这个 key 获取文件的二进制内容
header	Object		否	HTTP 请求 Header，Header 中不能设置 Referer
formData	Object		否	HTTP 请求中其他额外的 form data
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码如下：

wx.chooseImage({//调用选中图片接口
    success:function(res){
    var tempFilePaths = res.tempFilePaths;
    wx.uploadFile({
        url:'http://www.myserver.com',
        filePath:tempFilePath[0],
        name:'myFile',
        formData:{
            //其他数据
            'otherData':'value'
        },
    success:function(response){
        var data = response.data;//服务器返回数据
    }
    });
    }
});

wx.dwonloadFile(Object)

从服务端下载资源到本地，调用API后，客户端会直接发起一个HTTP GE请求，把文件下载到本地并返回文件的本地临时路径，临时文件在小程序本次启动期间都可以正常使用，如需要持久保存，需要主动调用wx.saveFile进行保存。下载文件最大并发限制为10个，默认超时时间和最大超时时间都是60S，Object参数属性如下：

属性	类型	默认值	必填	说明	最低版本
url	string		是	下载资源的 url
header	Object		否	HTTP 请求的 Header，Header 中不能设置 Referer
filePath	string		否	指定文件下载后存储的路径	1.8.0
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码如下：

wx.downloadFile({
    url:'http://www.myserver.com', //接口地址
    success:function(res){
        wx.getImageInfo({
        //下载图片资源后读取信息
        src:res.tempFilePath[0],
        success:function(info){
            console.log(info.width+","+info.height);
        }
        });
    } 
});

WebSocket

上面介绍的网络通信方法都是通过客户端主动向服务端发起请求，由服务端想要返回数据来达到通信目的，这个方式有缺点即不能实现服务端主动向客户端推送消息。采用这种短链接方式实现客户端和服务端之间的及时通信技术只能使用轮询，即在特定时间间隔（如每1秒），由客户端向服务端发起请求，然后由服务端返回最新的数据。这种方式处理即时通信时，既浪费性能又占带宽。面对这种情况，在需要即时通信时，我们可以使用小程序提供的WebSocket相关API创建WebSocket，实现长连接达到即时通信的目的。长连接服务端比短链接更耗资源，在技术选择上要慎重。

wx.connectSocket(Object)

创建一个WebSocket连接，一个小程序同时只能由一个WebSocket连接，创建新连接时，如果当前已存在一个WebSocket连接，会自动关闭该链接，并重新创建一个新的WebSocket连接，创建链接时默认和最大超时时间都是60秒，Object参数如下：

属性	类型	默认值	必填	说明	最低版本
url	string		是	开发者服务器 wss 接口地址
header	Object		否	HTTP Header，Header 中不能设置 Referer
protocols	Array.		否	子协议数组	1.4.0
tcpNoDelay	boolean	false	否	建立 TCP 连接的时候的 TCP_NODELAY 设置	2.4.0
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码如下：

wx.connectSocket({
    url:'wss://example.qq.com',
    header:{
        'content-type':'application/json'    
    },
    protocols:['protocoll'],
    method:'GET'
})

wx.onSocketOpen(callback)

监听WebSocket连接打开事件

示例代码如下：

wx.connectSocket({//创建连接
    url:'wss://www.myserver.com',
});
wx.onSocketOpen(function(res){
    console.log('socket连接已打开');
});

wx.onSocketError(callback)

监听WebSocket错误

示例代码如下：

wx.connectSocket({//建立连接
  url: 'wss://www.myserver.com',
});
wx.onSocketOpen(function(res){
  console.log('socket连接已打开');
});
wx.onSocketError(function(res){
  console.log('连接打开失败');
})

wx.sendSocketMessage(callback)

通过WebSocket连接发送数据，需要先通过wx.connectSocket连接后台，并在wx.onSocketOpen回调之后才能发送。Object参数属性如下：

属性	类型	默认值	必填	说明
data	string/ArrayBuffer		是	需要发送的内容
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码如下：

var socketOpen=false;
var socketMsgQueue =[];
wx.connectSocket({//建立连接
  url: 'wss://www.myserver.com',
});
wx.onSocketOpen(function(res){//监听连接打开
  socketOpen = true
  //链接打开后先处理之前栈中的数据
  for(var i=0,msg;msg=socketMsgQueue[i];i++){
    senMsg(msg);
  }
  socketMsgQueue=[];
});
function sendMsg(msg){
  //如果链接在请求中还未打开，先将数据压入信息栈中
  if(!socketOpen){
    socketMsgQueue.push(msg);
    return;
  }
  //如果链接已打开，直接发送数据
  wx.sendSocketMessage({
    data: msg
  })
}
sendMsg({
myName:'weixin'
});

wx.onSocketMessage(callback)

监听WebSocket接收到服务器的消息事件，callback返回参数为data，是服务器返回的消息

示例代码如下：

wx.connectSocket({
  url: 'wss://www.myserver.com',
});
wx.onSocketMessage(function(res){
  console.log('收到服务器内容:'+res.data);
});

wx.closeSocket()

关闭WebSocket连接

示例代码如下：

wx.closeSocket();

wx.onSocketClose(callback)

监听WebSocket是否关闭，当WebSocket成功关闭时触发

示例代码如下：

wx.connectSocket({
  url: 'wss://www.myserver.com',
});
/**
 * 这里关闭socket必须在成功打开后，
 * 如果由于网络或时效问题在成功打开前调用closeSocket，那么就做不到关闭WebSocket目的
 */
wx.onSocketOpen(function(){
  wx.closeSocket();
});
wx.onSocketClose(function(){
  console.log('连接已关闭');
});