• uni.request(OBJECT)

    uni.request(OBJECT)

    发起网络请求。

    在各个小程序平台运行时,网络相关的 API 在使用前需要配置域名白名单。

    OBJECT 参数说明

    参数名类型必填默认值说明平台差异说明
    urlString开发者服务器接口地址
    dataObject/String/ArrayBuffer请求的参数5+App(自定义组件编译模式)不支持ArrayBuffer类型
    headerObject设置请求的 header,header 中不能设置 Referer。
    methodStringGET有效值详见下方说明
    dataTypeStringjson如果设为 json,会尝试对返回的数据做一次 JSON.parse
    responseTypeStringtext设置响应的数据类型。合法值:text、arraybuffer5+App和支付宝小程序不支持
    successFunction收到开发者服务成功返回的回调函数
    failFunction接口调用失败的回调函数
    completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

    method 有效值

    必须大写,有效值在不同平台差异说明不同。

    method5+AppH5微信小程序支付宝小程序百度小程序头条小程序
    GET
    POST
    PUTx
    DELETExx
    CONNECTxxx
    HEADxx
    OPTIONSxx
    TRACExxx

    success 返回参数说明

    参数类型说明
    dataObject/String/ArrayBuffer开发者服务器返回的数据
    statusCodeNumber开发者服务器返回的 HTTP 状态码
    headerObject开发者服务器返回的 HTTP Response Header

    data 数据说明

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

    • 对于 GET 方法,会将数据转换为 query string。例如 { name: 'name', age: 18 } 转换后的结果是 name=name&age=18
    • 对于 POST 方法且 header['content-type']application/json 的数据,会进行 JSON 序列化。
    • 对于 POST 方法且 header['content-type']application/x-www-form-urlencoded 的数据,会将数据转换为 query string。示例
    1. uni.request({
    2. url: 'https://www.example.com/request', //仅为示例,并非真实接口地址。
    3. data: {
    4. text: 'uni.request'
    5. },
    6. header: {
    7. 'custom-header': 'hello' //自定义请求头信息
    8. },
    9. success: (res) => {
    10. console.log(res.data);
    11. this.text = 'request success';
    12. }
    13. });

    返回值

    如果希望返回一个 requestTask 对象,需要至少传入 success / fail / complete 参数中的一个。例如:

    1. var requestTask = uni.request({
    2. url: 'https://www.example.com/request', //仅为示例,并非真实接口地址。
    3. complete: ()=> {}
    4. });
    5. requestTask.abort();

    如果没有传入 success / fail / complete 参数,则会返回封装后的 Promise 对象:Promise 封装

    通过 requestTask,可中断请求任务。

    requestTask 对象的方法列表

    方法参数说明
    abort中断请求任务
    offHeadersReceived取消监听 HTTP Response Header 事件,仅微信小程序平台支持,文档详情
    onHeadersReceived监听 HTTP Response Header 事件。会比请求完成事件更早,仅微信小程序平台支持,文档详情

    示例

    1. const requestTask = uni.request({
    2. url: 'https://www.example.com/request', //仅为示例,并非真实接口地址。
    3. data: {
    4. name: 'name',
    5. age: 18
    6. },
    7. success: function(res) {
    8. console.log(res.data);
    9. }
    10. });
    11. // 中断请求任务
    12. requestTask.abort();

    Tips

    • 请求的 headercontent-type 默认为 application/json
    • 网络请求的 超时时间 可以统一在 manifest.json 中配置 networkTimeout。
    • H5 端本地调试需注意跨域问题,参考:调试跨域问题解决方案
    • 注意由于百度小程序iOS客户端,请求失败时会进入fail回调,需要针对百度增加相应的处理以解决该问题。
    • 注意非 H5 端不支持 cookie,服务器应避免验证 cookie。如果服务器无法修改,也可以使用一些模拟手段,比如这样的工具https://github.com/charleslo1/weapp-cookie
    • 按照 W3C 规范,H5 端无法获取 response header 中 Set-Cookie、Set-Cookie2 这2个字段,对于跨域请求,允许获取的 response header 字段只限于“simple response header”和“Access-Control-Expose-Headers”(详情)
    • uni-app 插件市场有flyio、axios等三方封装的拦截器可用
    • 低版本手机自身不支持 ipv6,如果服务器仅允许 ipv6,会导致老手机无法正常运行或访问速度非常慢
    • localhost、127.0.0.1等服务器地址,只能在电脑端运行,手机端连接时不能访问。请使用标准IP并保证手机能连接电脑网络
    • debug 模式,安卓端暂时无法获取响应头,url中含有非法字符(如未编码为%20的空格)时会请求失败

    发现错误?想参与编辑?在 GitHub 上编辑此页面!