# RequestTask wx.request(Object object)
以 Promise 风格 调用:不支持
小程序插件:支持,需要小程序基础库版本不低于 1.9.6
微信 Windows 版:支持
微信 Mac 版:支持
相关文档: 网络使用说明、局域网通信、移动解析HttpDNS
# 功能描述
发起 HTTPS 网络请求。使用前请注意阅读相关说明。
# 参数
# Object object
属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
url | string | 是 | 开发者服务器接口地址 | |||||||||||||||||||||
data | string/object/ArrayBuffer | 否 | 请求的参数 | |||||||||||||||||||||
header | Object | 否 | 设置请求的 header,header 中不能设置 Referer。content-type 默认为 application/json | |||||||||||||||||||||
timeout | number | 否 | 超时时间,单位为毫秒。默认值为 60000 | 2.10.0 | ||||||||||||||||||||
method | string | GET | 否 | HTTP 请求方法 | ||||||||||||||||||||
| ||||||||||||||||||||||||
dataType | string | json | 否 | 返回的数据格式 | ||||||||||||||||||||
| ||||||||||||||||||||||||
responseType | string | text | 否 | 响应的数据类型 | 1.7.0 | |||||||||||||||||||
| ||||||||||||||||||||||||
useHighPerformanceMode | boolean | false | 否 | 使用高性能模式,暂仅支持 Android,默认关闭。该模式下有更优的网络性能表现,更多信息请查看下方说明。 | 3.3.3 | |||||||||||||||||||
enableHttp2 | boolean | false | 否 | 开启 http2 | 2.10.4 | |||||||||||||||||||
enableProfile | boolean | true | 否 | 是否开启 profile,默认开启。开启后可在接口回调的 res.profile 中查看性能调试信息。 | ||||||||||||||||||||
enableQuic | boolean | false | 否 | 开启 Quic 协议(gQUIC Q43) | 2.10.4 | |||||||||||||||||||
enableCache | boolean | false | 否 | 开启 Http 缓存 | 2.10.4 | |||||||||||||||||||
enableHttpDNS | boolean | false | 否 | 是否开启 HttpDNS 服务。如开启,需要同时填入 httpDNSServiceId 。 HttpDNS 用法详见 移动解析HttpDNS | 2.19.1 | |||||||||||||||||||
httpDNSServiceId | string | 否 | HttpDNS 服务商 Id。 HttpDNS 用法详见 移动解析HttpDNS | 2.19.1 | ||||||||||||||||||||
enableChunked | boolean | false | 否 | 开启 transfer-encoding chunked。 | 2.20.2 | |||||||||||||||||||
forceCellularNetwork | boolean | false | 否 | 强制使用蜂窝网络发送请求 | 2.21.0 | |||||||||||||||||||
redirect | string | follow | 否 | 重定向拦截策略。(目前安卓、iOS、开发者工具已支持,PC端将在后续支持) | 3.2.2 | |||||||||||||||||||
| ||||||||||||||||||||||||
success | function | 否 | 接口调用成功的回调函数 | |||||||||||||||||||||
fail | function | 否 | 接口调用失败的回调函数 | |||||||||||||||||||||
complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
# object.success 回调函数
# 参数
# Object res
属性 | 类型 | 说明 | 最低版本 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | string/Object/Arraybuffer | 开发者服务器返回的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statusCode | number | 开发者服务器返回的 HTTP 状态码 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
header | Object | 开发者服务器返回的 HTTP Response Header | 1.2.0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cookies | Array.<string> | 开发者服务器返回的 cookies,格式为字符串数组 | 2.10.0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
profile | Object | 网络请求过程中一些调试信息,查看详细说明 | 2.10.4 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
exception | Object | 网络请求过程中的一些异常信息,例如httpdns重试等 | 3.0.0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
useHttpDNS | boolean | 最终请求是否使用了HttpDNS(仅当enableHttpDNS传true时返回此字段) | 3.4.10 |
# object.fail 回调函数
# 参数
# Object err
# 返回值
# RequestTask
基础库 1.4.0 开始支持,低版本需做兼容处理。
请求任务对象
# 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)...)
# useHighPerformanceMode 高性能模式说明
在该模式下,框架将会采用全新的网络请求模块,默认支持 HTTP3,可以提升小程序的网络请求性能。有以下注意事项:
- 除声明了
enableChunked
后会走 HTTP1 以外,均会自动开启 HTTP2/HTTP3 等优化能力,enableQuic
、enableHttp2
参数将会强制开启。建议开发者在后台服务也开启对应能力以获得更好的效果。 - 暂仅支持 Android,iOS/PC 端设置该参数后会使用原 request 模块。iOS 会在后续支持该参数。
- 暂不支持 forceCellularNetwork 参数。
- 暂不支持 HttpDNS 能力。
- 开启
enableProfile
后,返回的 profile 字段部分信息缺失,会被缺省值代替。缺失部分包括 redirectStart、redirectEnd、rtt、estimate_nettype、httpRttEstimate、transportRttEstimate、downstreamThroughputKbpsEstimate、throughputKbps、peerIP、port。
# 示例代码
wx.request({
url: 'example.php', //仅为示例,并非真实的接口地址
data: {
x: '',
y: ''
},
header: {
'content-type': 'application/json' // 默认值
},
success (res) {
console.log(res.data)
}
})