uni.request(param) @request

展示全部

# uni.request(param)

发起网络请求。 GitCode GitHub

# request 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

# 参数

名称类型必填默认值兼容性描述

param

RequestOptions<T>

是

网络请求参数

名称类型必备默认值兼容性描述

url

string

是

开发者服务器接口地址

data

any

否

null

请求的参数在app-android端，参数类型只能为UTSJSONObject或者string`类型,app-android平台从 4.51版本开始支持ArrayBuffer, app-ios平台从 4.61版本开始支持ArrayBuffer

header

UTSJSONObject

否

null

设置请求的 header，header 中不能设置 Referer

method

string

否

"GET"

请求方法

合法值

兼容性

描述

GET

GET方法请求一个指定资源的表示形式，使用 GET 的请求应该只被用于获取数据。

POST

POST方法用于将实体提交到指定的资源，通常导致在服务器上的状态变化或副作用。

PUT

PUT方法用有效载荷请求替换目标资源的所有当前表示。

PATCH

PATCH方法用于对资源应用部分修改。

DELETE

DELETE方法删除指定的资源。

HEAD

HEAD方法请求一个与GET请求的响应相同的响应，但没有响应体。

OPTIONS

OPTIONS 方法用于描述目标资源的通信选项。

timeout

number

否

60000

超时时间，单位 ms

withCredentials

boolean

否

跨域请求时是否携带凭证（cookies）

firstIpv4

boolean

否

false

DNS解析时优先使用ipv4

enableChunked

boolean

否

开启 transfer-encoding chunked。

success

(option: RequestSuccess<T>) => void

否

null

网络请求成功回调。

fail

(option: RequestFail) => void

否

null

网络请求失败回调。

complete

(option: any) => void

否

null

网络请求完成回调，成功或者失败都会调用。

# RequestSuccess<T> 的属性值

名称

类型

必备

默认值

兼容性

描述

data

否

开发者服务器返回的数据, app-android平台从 4.51版本开始支持ArrayBuffer, app-ios平台从 4.61版本开始支持ArrayBuffer

statusCode

number

是

开发者服务器返回的 HTTP 状态码

header

any

是

开发者服务器返回的 HTTP Response Header

Array<string>

是

开发者服务器返回的 cookies，格式为字符串数组

# RequestFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值

兼容性

描述

接口超时

1000

服务端系统错误

100001

json数据解析错误

100002

错误信息json解析失败

600003

网络中断

600008

data参数类型不合法

600009

URL格式不合法

602001

request系统错误

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# 返回值

类型
RequestTask

# RequestTask 的方法

# abort(): void

中断网络请求。

# abort 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

# onChunkReceived(listener: RequestTaskOnChunkReceivedCallback): number

监听 Transfer-Encoding Chunk Received 事件。

# onChunkReceived 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS	HarmonyOS uni-app x UTS 插件
4.71	4.41	4.71	4.71	4.71	4.71	4.71

# 参数

名称

类型

必填

默认值

兼容性

描述

listener

(result: RequestTaskOnChunkReceivedListenerResult) => void

是

# RequestTaskOnChunkReceivedListenerResult 的属性值

名称

类型

必备

默认值

兼容性

描述

data

ArrayBuffer

是

返回的chunk buffer

# 返回值

类型
number

# offChunkReceived(listener ?: number | RequestTaskOnChunkReceivedCallback | null): void

移除 Transfer-Encoding Chunk Received 事件的监听函数。

# offChunkReceived 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS	HarmonyOS uni-app x UTS 插件
4.71	4.41	4.71	4.71	4.71	4.71	4.71

# 参数

名称

类型

必填

默认值

兼容性

描述

listener

number | (result: RequestTaskOnChunkReceivedListenerResult) => void

否

# onHeadersReceived(listener: RequestTaskOnHeadersReceivedCallback): number

监听 HTTP Response Header 事件。

# onHeadersReceived 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS	HarmonyOS uni-app x UTS 插件
4.71	4.41	4.71	4.71	4.71	4.71	4.71

# 参数

名称

类型

必填

默认值

兼容性

描述

listener

(result: RequestTaskOnHeadersReceivedListenerResult) => void

是

HTTP Response Header 事件的监听函数

# RequestTaskOnHeadersReceivedListenerResult 的属性值

名称

类型

必备

默认值

兼容性

描述

Array<string>

是

开发者服务器返回的 cookies，格式为字符串数组

header

UTSJSONObject

是

开发者服务器返回的 HTTP Response Header

statusCode

number

是

开发者服务器返回的 HTTP 状态码（目前开发者工具上不会返回 statusCode 字段，可用真机查看该字段，后续将会支持）

# 返回值

类型
number

# offHeadersReceived(listener ?: number | RequestTaskOnHeadersReceivedCallback | null): void

移除 HTTP Response Header 事件的监听函数。

# offHeadersReceived 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS	HarmonyOS uni-app x UTS 插件
4.71	4.41	4.71	4.71	4.71	4.71	4.71

# 参数

名称

类型

必填

默认值

兼容性

描述

listener

number | (result: RequestTaskOnHeadersReceivedListenerResult) => void

否

# 参见

# 示例

hello uni-app x

Template

Script

<template>
  <view style="flex: 1;">
    <view class="uni-padding-wrap uni-common-mt">
      <view class="uni-common-mt" style="border-width: 2px;border-style: solid; border-radius: 4px;">
        <textarea :value="res" class="uni-textarea" style="width: 100%"></textarea>
      </view>
      <view>
        <text>地址 : {{ host + url}}</text>
        <text>请求方式 : {{method}}</text>
      </view>
      <view class="uni-btn-v uni-common-mt">
        <button type="primary" @click="sendRequest">发起请求</button>
      </view>
    </view>
    <scroll-view style="flex: 1;" show-scrollbar="true">
      <view style="padding: 20px;">
        <text>设置请求方式</text>
        <view class="uni-common-pb"></view>
        <view style="flex-direction: row;flex-wrap: wrap;">
          <button style="padding: 5px; margin-right: 10px;" type="primary" size="mini"
            @click="changeMethod('GET')">GET</button>
          <button style="padding: 5px; margin-right: 10px; " type="primary" size="mini"
            @click="changeMethod('POST')">POST</button>
          <button style="padding: 5px; margin-right: 10px; " type="primary" size="mini"
            @click="changeMethod('PUT')">PUT</button>
          <button style="padding: 5px; margin-right: 10px;" type="primary" size="mini"
            @click="changeMethod('DELETE')">DELETE</button>
          <button style="padding: 5px; margin-right: 10px; " type="primary" size="mini"
            @click="changeMethod('PATCH')">PATCH</button>
          <button style="padding: 5px;margin-right: 10px;" type="primary" size="mini"
            @click="changeMethod('OPTIONS')">OPTIONS</button>
          <button style="padding: 5px;" type="primary" size="mini" @click="changeMethod('HEAD')">HEAD</button>
        </view>
      </view>
      <view style="padding: 20px;">
        <text>请求返回错误码的接口（默认为GET）</text>
        <view class="uni-common-pb"></view>
        <view style="flex-direction: row;flex-wrap: wrap;">
          <button style="padding: 5px;" type="primary" size="mini" v-for="(item, index) in errorCodeUrls" :key="index"
            @click="changeUrl(item)">{{item}}</button>
        </view>
      </view>
      <view style="padding: 20px;">
        <text>请求不同header的接口（默认为GET）</text>
        <view class="uni-common-pb"></view>
        <view style="flex-direction: row;flex-wrap: wrap;">
          <button style="padding: 5px;" type="primary" size="mini" v-for="(item, index) in headerUrls" :key="index"
            @click="changeUrl(item)">{{item}}</button>
        </view>
      </view>
      <view style="padding: 20px;">
        <text>请求不同content-type的接口（默认为GET）</text>
        <view class="uni-common-pb"></view>
        <view style="flex-direction: row;flex-wrap: wrap;">
          <button style="padding: 5px;" type="primary" size="mini" v-for="(item, index) in contentTypeUrls" :key="index"
            @click="changeUrl(item)">{{item}}</button>
        </view>
      </view>

      <view style="padding: 20px;">
        <text>POST请求(有body)</text>
        <view class="uni-common-pb"></view>
        <view style="flex-direction: row;flex-wrap: wrap;">
          <button style="padding: 5px;" type="primary" size="mini" v-for="(item, index) in postUrls" :key="index"
            @click="changeUrlFromPost(item)">{{item}}</button>
        </view>
      </view>
      <!-- #ifdef APP || MP-WEIXIN || WEB -->
      <view style="padding: 20px;">
        <text>ArrayBuffer 测试</text>
        <view class="uni-common-pb"></view>
        <view style="flex-direction: row;flex-wrap: wrap;">
          <button style="padding: 5px;" type="primary" size="mini"
            @click="sendArrayBuffer(false)">请求body为ArrayBuffer，response也为ArrayBuffer</button>
          <button style="padding: 5px;" type="primary" size="mini"
            @click="sendArrayBuffer(true)">请求response为ArrayBuffer</button>
        </view>
      </view>
      <!-- #endif -->

      <view style="padding: 20px;">
        <text>RequestTask 测试</text>
        <view class="uni-common-pb"></view>
        <button type="primary" @click="sendChunkRequest">流式请求</button>
      </view>
      <view class="uni-common-pb"></view>
      <view class="uni-common-pb"></view>
    </scroll-view>
  </view>
</template>


<style>
  .uni-textarea {
    padding: 9px;
    font-size: 14px;
  }
</style>

# cookie管理

uni.request、uni.uploadFile、uni.downloadFile等网络API之间支持共享cookie Cookie共享介绍。

# 流式响应

AI大语言模型的服务器，向客户端持续的流式输出AI推理的结果文本。在客户端表现为打字机效果。

在uni-app x中，实现AI聊天的方式如下：

使用uni.request，把客户端的prompt通过POST的方式发送到LLM服务器，同时设置响应体格式为arraybuffer
客户端监听onChunkReceived事件，流式接收arraybuffer数据
客户端通过TextEncoder解码出文本，一般是markdown格式。（注意小程序自身没有TextEncoder，需要再通过三方库解码）
客户端流式渲染markdown格式

实现AI聊天的工作较为复杂，流式接收和渲染markdown很容易引发性能问题，处理原生的markdown解析工作量也很大。所以DCloud提供了开源的uni-ai x，已完整实现原生的、全端的AI聊天，详见

# JSON解析注意

由于uni-app x的强类型，导致联网获取JSON，拿到的不是js的object。

默认返回的是UTSJSONObject，UTSJSONObject是UTS提供的JSON数据对象，实现了js的object的JSON相关功能，但又有区别。如果照搬js的object用法会失败。

同时request也支持泛型，返回一个开发者自定义的type。

请不熟悉强类型的开发者务必阅读教程：uni-app x的联网教程

# 注意事项

拦截器在js中使用很普通，但原生语言由于缺少动态性，模拟实现拦截达不到js的全部效果。一般建议开发者直接使用uni.request，不封装拦截器。如仍想使用拦截器，见插件市场
app-android平台 request 接口如需包装和传递泛型，需参考泛型传递丢失注意。成熟的拦截器插件均已自动处理这些问题。
如果使用泛型先创建RequestOptions实例，再传入uni.request()，此时请务必确保request要显式指定泛型，例：

const options: RequestOptions<Person> = ...
uni.request<Person>(options)

app-android、app-ios平台 uni.request()暂未支持Promise，返回值是RequestTask。
web平台 request接口目前不支持创建传入的泛型的实例
web平台 request接口在 4.01版本之前返回数据是一个普通对象，4.01起调整为UTSJSONObject类型
在4.25版本iOS平台增加了Task原生对象自动销毁的逻辑，即网络请求完成后自动释放原生的Task对象，建议开发者在complete回调中置空Task对象，例

complete: () => {
            this.task = null
          },

如不释放，在调用Task对象的方法将导致控制台报错： error: instance object does not exist: id:15

# 通用类型

# GeneralCallbackResult

名称

类型

必备

默认值

兼容性

描述

errMsg

string

是

错误信息

运营产品

uni-ad uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001