uni-app——网络API

uni-app 网络API

在 uni-app 开发中，网络请求是获取数据与和服务器交互的重要手段。以下介绍 uni-app 中常见的网络 API，包括发起请求、上传和下载以及 WebSocket、UDP 通信等方面。

发起请求

在 uni-app 里，使用uni.request(OBJECT)来发起网络请求，它类似于传统 Web 开发中的 AJAX，在实际开发中主要用于从服务器端接口获取数据，其使用方式和 jQuery 的 AJAX 较为相似。下面详细介绍其参数：

url（必填）：这是开发者服务器接口的地址，明确请求的目标位置。
data：用于设置请求参数，这些参数会被发送到服务器。
header：用来设置请求的头部信息，比如设置认证信息等。
method：指定请求的方法，默认是 GET。
timeout：设置请求的超时时间，避免请求长时间无响应。
dataType：若设置为 json，uni-app 会自动尝试对返回的数据进行 JSON.parse 处理，方便后续使用数据。
sslVerify：用于验证 SSL 证书，保障请求的安全性。
withCredentials：决定跨域请求时是否携带凭证。
firstlpv4：在 DNS 解析时优先使用 IPV4。
success：当成功收到开发者服务器返回的数据时，会触发这个回调函数。
fail：一旦接口调用失败，就会进入这个回调函数。
complete：无论接口调用成功与否，结束时都会执行此回调函数。

代码示例

假设我们要从服务器获取用户列表数据，接口地址为https://example.com/api/users，示例代码如下：

uni.request({url: 'https://example.com/api/users',method: 'GET',data: {page: 1,limit: 10},header: {'Content-Type': 'application/json'},success: function (res) {console.log('请求成功', res.data);},fail: function (err) {console.log('请求失败', err);},complete: function () {console.log('请求结束');}
});

关于 data 的转换规则

发送给服务器的 data 必须是 String 类型，如果不是 String 类型，会按照特定规则强制转换为 String：

GET 方法：数据会被转换为查询字符串。例如{name:‘name’,age:‘18’}会转换为name=name&age=18。
POST 方法：
- 当header[‘content-type’]为application/json时，数据会进行 JSON 序列化。
- 当header[‘content-type’]为application/x-www-form-urlencoded时，数据会被转换为查询字符串。

method 的取值

method可取值有GET、POST、PUT、DELETE、CONNECT、HEAD、OPTIONS、TRACE。在实际开发中，常用且兼容性较好的是GET和POST方法。GET一般用于获取数据，POST常用于向服务器提交数据。

success 回调参数说明

data：类型可以是Object、String或者ArrayBuffer，这是开发者服务器返回的数据内容。
statusCode：是一个Number类型，代表开发者服务器返回的 HTTP 状态码，比如常见的 200 表示成功，404 表示未找到资源等。
header：是一个Object，包含开发者服务器返回的 HTTP Response Header 信息。
cookies：是一个字符串数组Array.，里面存储着开发者服务器返回的 cookies。

上传文件

使用uni.uploadFile(OBJECT)可以将本地资源上传到开发者服务器中。这个操作本质上是由客户端发起一个 POST 请求，且其content-type为multipart/form-data。下面介绍其参数：

url（必填）：这是开发者服务器的 URL，明确上传的目标服务器地址。
files（必填）：这是上传的文件列表。当使用files时，filePath和name这两个参数将不生效。
fielType：指定文件类型，可取值为image、video、audio等。
file：要上传的具体文件对象。
filePath（必填）：上传文件在本地的资源路径。
name：文件在服务器端对应的 key。
header：设置 HTTP 请求的 header 信息。
timeout：设置上传请求的超时时间。
formData：用于设置 HTTP 请求中的其他表单数据。
success、fail、complete：这三个回调函数分别在上传成功、失败以及结束时触发，方便开发者进行相应处理。

代码示例

假设要将本地的一张图片上传到服务器，服务器接口地址为https://example.com/api/upload，示例代码如下：

const filePath = '/storage/emulated/0/DCIM/Camera/IMG_20230101.jpg';
uni.uploadFile({url: 'https://example.com/api/upload',filePath: filePath,name: 'file',formData: {'user_id': '12345'},success: function (res) {console.log('上传成功', res.data);},fail: function (err) {console.log('上传失败', err);},complete: function () {console.log('上传结束');}
});