QinJs 官网 | QinJs 官网

qin.request(OBJECT)

发起网络请求。

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

OBJECT 参数说明

参数名	类型	必填	默认值	说明	平台差异说明
url	String	是		开发者服务器接口地址
data	Object/String/ArrayBuffer	否		请求的参数
header	Object	否		设置请求的 header，header 中不能设置 Referer	H5 端会自动带上 cookie ，且 H5 端不可手动修改
method	String	否	GET	有效值详见下方说明
timeout	Number	否	60000	超时时间，单位 ms	H5、微信小程序（2.10.0）
dataType	String	否	json	如果设为 json ，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
responseType	String	否	text	设置响应的数据类型。合法值： text 、 arraybuffer
enableHttp2	Boolean	否	false	开启 http2	微信小程序
enableQuic	Boolean	否	false	开启 quic	微信小程序
enableCache	Boolean	否	false	开启 cache	微信小程序、抖音小程序 2.31.0+
enableHttpDNS	Boolean	否	false	是否开启 HttpDNS 服务。如开启，需要同时填入 httpDNSServiceId 。 HttpDNS 用法详见移动解析HttpDNS	微信小程序
httpDNSServiceId	String	否		HttpDNS 服务商 Id 。 HttpDNS 用法详见移动解析HttpDNS	微信小程序
enableChunked	Boolean	否	false	开启 transfer-encoding chunked	微信小程序
forceCellularNetwork	Boolean	否	false	wifi 下使用移动网络发送请求	微信小程序
enableCookie	Boolean	否	false	开启后可在 headers 中编辑 cookie
cloudCache	Object/Boolean	否	false	是否开启云加速（详见云加速服务）
defer	Boolean	否	false	控制当前请求是否延时至首屏内容渲染后发送
success	Function	否		收到开发者服务器成功返回的回调函数
fail	Function	否		接口调用失败的回调函数
complete	Function	否		接口调用结束的回调函数（调用成功、失败都会执行）

method 有效值

注意：method 有效值必须大写，每个平台支持的 method 有效值不同，详细见下表。

method	H5	微信小程序	小红书小程序	抖音小程序	快手小程序
GET	√	√	√	√	√
POST	√	√	√	√	√
PUT	√	√	√	√	x
DELETE	√	√	√	x	x
CONNECT	√	√	x	x	x
HEAD	√	√	x	x	x
OPTIONS	√	√	x	x	x
TRACE	√	√	x	x	x

success 返回参数说明

参数	类型	说明
data	Object/String/ArrayBuffer	开发者服务器返回的数据
statusCode	Number	开发者服务器返回的 HTTP 状态码
header	Object	开发者服务器返回的 HTTP Response Header
cookies	Array<string>	开发者服务器返回的 cookies，格式为字符串数组

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。

示例

qin.request({
  //仅为示例，并非真实接口地址。
  url: 'https://www.example.com/request',
  data: {
    text: 'qin.request'，
  },
  header: {
    //自定义请求头信息
    'custom-header': 'hello',
  },
  success: (res) => {
    console.log(res.data);
    this.text = 'request success';
  },
});

qin.request({
  //仅为示例，并非真实接口地址。
  url: 'https://www.example.com/request',
  data: {
    text: 'qin.request'，
  },
  header: {
    //自定义请求头信息
    'custom-header': 'hello',
  },
  success: (res) => {
    console.log(res.data);
    this.text = 'request success';
  },
});

返回值

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

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

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

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

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

requestTask 对象的方法列表

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

示例

const requestTask = qin.request({
  //仅为示例，并非真实接口地址。
  url: 'https://www.example.com/request',
  data: {
    name: 'name',
    age: 18,
  },
  success: function(res) {
    console.log(res.data);
  },
});

// 中断请求任务
requestTask.abort();

const requestTask = qin.request({
  //仅为示例，并非真实接口地址。
  url: 'https://www.example.com/request',
  data: {
    name: 'name',
    age: 18,
  },
  success: function(res) {
    console.log(res.data);
  },
});

// 中断请求任务
requestTask.abort();

Tips

请求的 header 中 content-type 默认为 application/json。
避免在 header 中使用中文，或者使用 encodeURIComponent 进行编码，否则在百度小程序报错。（来自：快狗打车前端团队）
网络请求的 超时时间 可以统一在 manifest.json 中配置 networkTimeout。
H5 端本地调试需注意跨域问题，参考：调试跨域问题解决方案
注意小程序端不支持自动保持 cookie，服务器应避免验证 cookie。如果服务器无法修改，也可以使用一些模拟手段，比如这样的工具https://github.com/charleslo1/weapp-cookie 可以请求时带上 cookie 并将响应的 cookie 保存在本地。
H5 端 cookie 受跨域限制（和平时开发网站时一样），旧版的 qin.request 未支持 withCredentials 配置，可以直接使用 xhr 对象或者其他类库。
根据 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 的空格）时会请求失败
单次网络请求数据量建议控制在 50K 以下（仅指 json 数据，不含图片），过多数据应分页获取，以提升应用体验。

qin.request(OBJECT) ​

qin.request(OBJECT)