微信小程序学习总结(六) --- API

微信小程序学习总结(六) — API

API
规则:

1 . 都是以wx.开头
2. 以wx.on开头的是监听某个事件的API接口,接受一个回调函数作为参数
3. api大多是异步的函数,接受Object作为参数 success成功后的回调 fail失败后的回调 complete完成后的回调
4. wx.get获取宿主环境数据的接口
5. wx.set写入到宿主环境的数据接口
6. 调用函数时有两种方式:
直调函数: 在程序运行时立即执行被调函数
回调函数: 在程序运行后再执行被调函数

一. 网络请求

wx.request(Object) 发起HTTPS网络请求

  属性	           类型  	         默认值	        是否必填	               说明
  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	           否	        响应的数据类型
  success	     function	                           否	        接口调用成功的回调函数	
  fail	         function	                      	   否        	接口调用失败的回调函数	
  complete       function                              否           接口调用结束的回调函数（调用成功、失败都会执行）

object.method 的合法值

  值	           说明
  OPTIONS	HTTP 请求 OPTIONS
  GET	    HTTP 请求 GET
  HEAD	    HTTP 请求 HEAD
  POST   	HTTP 请求 POST
  PUT	    HTTP 请求 PUT
  DELETE	HTTP 请求 DELETE
  TRACE	    HTTP 请求 TRACE
  CONNECT	HTTP 请求 CONNECT

object.dataType 的合法值

  值	                 说明
  json	  返回的数据为 JSON，返回后会对返回的数据进行一次 JSON.parse
  其他	  不对返回的内容进行 JSON.parse

object.responseType 的合法值

  值	                  说明
  text	             响应的数据为文本
  arraybuffer        响应的数据为 ArrayBuffer

object.success 回调函数 (参数) Object res

  属性	                  类型                            说明	
  data	       string/Object/Arraybuffer	     开发者服务器返回的数据	
  statusCode	         number	                 开发者服务器返回的 HTTP 状态码	
  header	             Object	                 开发者服务器返回的 HTTP Response Header

返回值
RequestTask 请求任务对象
RequestTask.abort() 中断请求任务

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

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

二. 上传下载

1. 上传UploadTask wx.uploadFile(Object object)

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

参数( Object 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		否	        接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数 参数 (Object res)

    属性	      类型        	  说明
    data	    string	  开发者服务器返回的数据	
    statusCode	number	  开发者服务器返回的 HTTP 状态码	

返回值 UploadTask
一个可以监听上传进度进度变化的事件和取消上传的对象

方法:
UploadTask.abort()
中断上传任务

UploadTask.onProgressUpdate(function callback)
监听上传进度变化事件

function callback
上传进度变化事件的回调函数 参数 Object res

 属性	                     类型	       说明
 progress	                number	  上传进度百分比	
 totalBytesSent	            number    已经上传的数据长度，单位 Bytes	
 totalBytesExpectedToSend	number    预期需要上传的数据总长度，单位 Bytes

2. 下载 DownloadTask wx.downloadFile (Object object)

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

注意：请在服务端响应的 header 中指定合理的 Content-Type 字段，以保证客户端正确处理文件类型。

参数 (Object object)

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

object.success 回调函数 参数 (Object res)

  属性	          类型	               说明
  tempFilePath	 string	    临时文件路径。如果没传入 filePath 指定文件存储路径，则下载后的文件会存储到一个临时文件	
  statusCode	 number  	开发者服务器返回的 HTTP 状态码	

返回值 DownloadTask

一个可以监听下载进度变化事件和取消下载的对象
方法
DownloadTask.abort() 中断下载任务

DownloadTask.onProgressUpdate(function callback) 监听下载进度变化事件

参数 (Object res)

 属性                  	     类型	      说明
 progress	                number	 下载进度百分比	
 totalBytesWritten	        number	 已经下载的数据长度，单位 Bytes	
 totalBytesExpectedToWrite	number	 预期需要下载的数据总长度，单位 Bytes

三. WebSocket

①SocketTask wx.connectSocket(Object object) 创建一个 WebSocket 连接

参数 (Object object)

 属性	        类型	  是否必填	              说明
 url	       string		 是	          开发者服务器 wss 接口地址	
 header	       Object		 否	          HTTP Header，Header 中不能设置 Referer	
 protocols	Array.<string>		 否	      子协议数组
 success	  function		 否	          接口调用成功的回调函数	
 fail	      function		 否	          接口调用失败的回调函数	
 complete	  function		 否	          接口调用结束的回调函数（调用成功、失败都会执行）	

返回值: SocketTask

WebSocket 任务，可通过 wx.connectSocket() 接口创建返回

方法
1 SocketTask.send(Object object) 通过 WebSocket 连接发送数据

2 SocketTask.close(Object object) 关闭 WebSocket 连接

3 SocketTask.onOpen(function callback) 监听WebSocket 连接打开事件

4 SocketTask.onClose(function callback) 监听WebSocket 连接关闭事件

5 SocketTask.onError(function callback) 监听WebSocket 错误事件

6 SocketTask.onMessage(function callback) 监听WebSocket 接受到服务器的消息事件

注意: 最多可以同时存在 5（小游戏）/2（小程序）个 WebSocket 连接。

②wx.closeSocket(Object object) 关闭 WeSocket 连接

参数 (Object object)

 属性	    类型           默认值	         是否必填              	   说明
 code	   number	1000（表示正常关闭连接）	    否	    一个数字值表示关闭连接的状态号，表示连接被关闭的原因。	
 reason	   string                               否	    一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本（不是字符）。	
 success   function                             否	    接口调用成功的回调函数	
 fail	   function		                        否	    接口调用失败的回调函数	
 complete  function                             否	    接口调用结束的回调函数（调用成功、失败都会执行）

③wx.sendSocketMessage(Object object)通过WebSocket连接发送数据

发送数据, 需要先 wx.connectSocket ，并在 wx.onSocketOpen 回调之后才能发送

参数 (Object object)

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

④wx.onSocketOpen (function callback) 监听WebSocket** 连接打开事件**
参数 (function callback) WebSocket 连接打开事件的回调函数
参数 (Object res)

  属性	     类型	           说明
  header	object	连接成功的 HTTP 响应 Header

⑤wx.onSocketClose(function callback) 监听WebSocket连接关闭事件
参数 (function callback) WebSocket 连接关闭事件的回调函数

⑥wx.onSocketMessage (function callback) 监听WebSocket 接受到服务器的消息事件
参数 (function callback) WebSocket 接受到服务器的消息事件的回调函数
参数 (Object res)

 属性	       类型	             说明
 data	string/ArrayBuffer	服务器返回的消息

⑦wx.onSocketError (function callback) 监听WebSocket错误事件
参数 (function callback) WebSocket 错误事件的回调函数