uni-halo/.agents/bak-skills/uniappx-project/references/api/network.md

网络请求 API

uni.request

发起网络请求。

参数

参数名	类型	必填	说明	平台差异说明
url	String	是	开发者服务器接口地址	-
data	Object/String/ArrayBuffer	否	请求的参数	-
header	Object	否	设置请求的 header，header 中不能设置 Referer	-
method	String	否	HTTP 请求方法，默认为 GET	-
timeout	Number	否	超时时间，单位为 ms，默认为 60000	-
dataType	String	否	如果设为 json，会尝试对返回的数据做一次 JSON.parse	-
responseType	String	否	设置响应的数据类型，默认为 text	-
sslVerify	Boolean	否	验证 ssl 证书	App
withCredentials	Boolean	否	跨域请求时是否携带凭证（cookies）	H5
firstIpv4	Boolean	否	DNS 解析时优先使用 ipv4	App

返回值

参数名	类型	说明
data	Object/String/ArrayBuffer	服务器返回的数据
statusCode	Number	HTTP 状态码
header	Object	服务器返回的 header
cookies	Array	服务器返回的 cookies

平台支持

平台	支持情况
H5	✅
微信小程序	✅
支付宝小程序	✅
百度小程序	✅
字节跳动小程序	✅
QQ 小程序	✅
快手小程序	✅
App	✅
快应用	✅

示例

// GET 请求
uni.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  data: {
    id: 123
  },
  success: (res) => {
    console.log(res.data)
  },
  fail: (err) => {
    console.error(err)
  }
})

// POST 请求
uni.request({
  url: 'https://api.example.com/data',
  method: 'POST',
  data: {
    name: 'John',
    age: 30
  },
  header: {
    'Content-Type': 'application/json'
  },
  success: (res) => {
    console.log(res.data)
  }
})

// 使用 Promise
uni.request({
  url: 'https://api.example.com/data'
}).then(res => {
  console.log(res.data)
}).catch(err => {
  console.error(err)
})

uni.uploadFile

上传文件。

参数

参数名	类型	必填	说明	平台差异说明
url	String	是	开发者服务器 url	-
filePath	String	是	要上传文件资源的路径	-
name	String	是	文件对应的 key，开发者在服务端可以通过这个 key 获取文件的二进制内容	-
header	Object	否	HTTP 请求 Header，header 中不能设置 Referer	-
formData	Object	否	HTTP 请求中其他额外的 form data	-
timeout	Number	否	超时时间，单位为 ms，默认为 60000	-

返回值

参数名	类型	说明
data	String	服务器返回的数据
statusCode	Number	HTTP 状态码

平台支持

平台	支持情况
H5	✅
微信小程序	✅
支付宝小程序	✅
百度小程序	✅
字节跳动小程序	✅
QQ 小程序	✅
快手小程序	✅
App	✅
快应用	❌

示例

uni.chooseImage({
  count: 1,
  success: (res) => {
    const tempFilePaths = res.tempFilePaths
    uni.uploadFile({
      url: 'https://api.example.com/upload',
      filePath: tempFilePaths[0],
      name: 'file',
      formData: {
        'user': 'test'
      },
      success: (uploadRes) => {
        console.log(uploadRes.data)
      },
      fail: (err) => {
        console.error(err)
      }
    })
  }
})

uni.downloadFile

下载文件。

参数

参数名	类型	必填	说明	平台差异说明
url	String	是	下载资源的 url	-
header	Object	否	HTTP 请求 Header，header 中不能设置 Referer	-
timeout	Number	否	超时时间，单位为 ms，默认为 60000	-

返回值

参数名	类型	说明
tempFilePath	String	临时文件路径，下载后的文件会存储到一个临时文件
statusCode	Number	HTTP 状态码

平台支持

平台	支持情况
H5	✅
微信小程序	✅
支付宝小程序	✅
百度小程序	✅
字节跳动小程序	✅
QQ 小程序	✅
快手小程序	✅
App	✅
快应用	❌

示例

uni.downloadFile({
  url: 'https://example.com/file.pdf',
  success: (res) => {
    if (res.statusCode === 200) {
      console.log('下载成功', res.tempFilePath)
      // 可以调用 uni.openDocument 打开文件
      uni.openDocument({
        filePath: res.tempFilePath,
        success: () => {
          console.log('打开文档成功')
        }
      })
    }
  },
  fail: (err) => {
    console.error('下载失败', err)
  }
})

uni.connectSocket

创建 WebSocket 连接。

参数

参数名	类型	必填	说明	平台差异说明
url	String	是	服务器接口地址，必须是 wss 协议，且域名必须是后台配置的合法域名	-
header	Object	否	HTTP Header，header 中不能设置 Referer	-
protocols	Array	否	子协议数组	H5
method	String	否	请求方法	App

平台支持

平台	支持情况
H5	✅
微信小程序	✅
支付宝小程序	✅
百度小程序	✅
字节跳动小程序	✅
QQ 小程序	✅
快手小程序	✅
App	✅
快应用	❌

示例

// 创建 WebSocket 连接
uni.connectSocket({
  url: 'wss://example.com/websocket',
  success: () => {
    console.log('连接成功')
  }
})

// 监听 WebSocket 连接打开事件
uni.onSocketOpen((res) => {
  console.log('WebSocket 连接已打开')
})

// 监听 WebSocket 错误事件
uni.onSocketError((res) => {
  console.error('WebSocket 错误', res)
})

// 发送数据
uni.sendSocketMessage({
  data: JSON.stringify({
    type: 'message',
    content: 'Hello'
  })
})

// 监听接收消息
uni.onSocketMessage((res) => {
  console.log('收到消息', res.data)
})

// 关闭连接
uni.closeSocket()

参考资源

• uni-app 网络请求文档
• uni-app 文件上传文档
• uni-app 文件下载文档
• uni-app WebSocket 文档