tt.request
收藏我的收藏
收藏基础库 1.0.0 开始支持本方法，这是一个异步方法。
发起一个网络请求。
| 前提条件 | 网络相关的 API 在使用前需要配置域名白名单，请前往开发者平台 「开发 - 开发设置」，添加 request 合法域名 |
| 业务背景 | 无 |
| 使用限制 |
|
| 注意事项 | 无 |
| 相关教程 |
语法
tt.request(options)
参数说明
options 为 object 类型，属性如下：
| 属性名 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
|---|---|---|---|---|---|
| url | string | 是 | 请求地址 | 1.0.0 | |
| header | object | {"content-type": "application/json"} | 否 | 请求 Header | 1.0.0 |
| method | enum | GET | 否 | 网络请求方法 | 1.0.0 |
| data | object | 是 | 请求的参数。object / array / ArrayBuffer 类型 | 1.0.0 | |
| dataType | string | json | 否 | 期望返回的数据类型，支持 json、string | 1.0.0 |
| responseType | string | text | 否 | 期望响应的数据类型，支持 text 或 arraybuffer | 1.0.0 |
| timeout | number | 否 | 接口超时时间，单位为毫秒，不传默认取 game.json 中的 networkTimeout 配置 | 3.83.0 | |
| enableProfile | boolean | true | 否 | 是否开启 profile，默认开启。开启后可在接口回调的 res.profile 中查看性能调试信息。IDE 未支持该能力，请使用真机调试。 | 3.83.0 |
| redirect | enum | follow | 否 | 重定向拦截策略 | 3.83.0 |
| enableCache | boolean | false | 否 | 开启 HTTP 缓存 | 3.83.0 |
| success | function | 否 | 接口调用成功的回调函数 | 1.0.0 | |
| fail | function | 否 | 接口调用失败的回调函数 | 1.0.0 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） | 1.0.0 |
header 参数说明
referer
网络请求 header 中的 referer 不可设置。 其固定格式为：https://tmaservice.developer.toutiao.com?appid={appid}&version={appVersion}，其中 appid为小游戏的 APPID，appVersion为小游戏的版本号。
user-agent
网络请求 header 中的 user-agent 不可设置。 其固定格式分为：
- IOS 系统：[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] webview/[插件版本]。
- Android 系统：[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] PluginVersion/[插件版本]。
data 参数说明
传给服务器的数据最终会是 String 类型，如果 data 不是 String 类型，会被转换成 String 。转换规则如下：
- 如果数据类型是 string 或者是 arraybuffer，则直接返回该数据；
- 如果 header['content-type'] 是 application/x-www-form-urlencoded，会将数据转换成 query string： encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...，然后返回该数据。
- 如果 header['content-type'] 是 application/json，则会对数据进行 JSON 序列化，然后返回该数据。
- 如果数据类型是 object，则会对数据进行 JSON 序列化，然后返回该数据。
- 如果是其他情况，则直接调用数据的 toString()， 然后返回该数据。
method 的合法值
| 值 | 说明 | 最低支持版本 |
|---|---|---|
| GET | GET 请求 | 1.0.0 |
| OPTIONS | OPTIONS 请求 | 1.0.0 |
| HEAD | HEAD 请求 | 1.0.0 |
| POST | POST 请求 | 1.0.0 |
| PUT | PUT 请求 | 1.0.0 |
| DELETE | DELETE 请求 | 1.0.0 |
redirect 的合法值
| 值 | 说明 | 最低支持版本 |
|---|---|---|
| follow | 不拦截重定向，即客户端自动处理重定向 | 3.83.0 |
| manual | 拦截重定向。开启后，当 http 状态码为 3xx 时客户端不再自动重定向，而是触发 onHeadersReceived 回调，并结束本次 request 请求。 | 3.83.0 |
回调成功
object 类型，属性如下：
| 属性名 | 类型 | 说明 | 最低支持版本 |
|---|---|---|---|
| statusCode | number | 返回的 HTTP 状态码 | 1.0.0 |
| header | object | 返回的 HTTP Response Header | 1.0.0 |
| data | string | 返回的数据，类型取决于 dataType 和 responseType 参数 | 1.0.0 |
| errMsg | string | "request:ok" | 1.0.0 |
回调失败
object 类型，属性如下：
| 属性名 | 类型 | 说明 | 最低支持版本 |
|---|---|---|---|
| errMsg | string | "request:fail " + 详细错误信息 | 1.0.0 |
返回值
| 类型 | 说明 | 最低支持版本 |
|---|---|---|
| object | RequestTask(网络请求任务对象)，调用 tt.request 后返回的请求对象。 | 1.0.0 |
错误码
| errNo | errMsg | 说明 | 最低支持版本 |
|---|---|---|---|
| 20001 | invalid param | 参数错误 | 1.0.0 |
| 10401 | internal error | 小游戏框架内部错误，有需要请创建工单咨询 | 1.0.0 |
| 10402 | internal error | 小游戏框架内部错误，有需要请创建工单咨询 | 1.0.0 |
| 21100 | url not in domain list, url == %s | 1.0.0 | |
| 21100 | url is invalid, url == %s | 1.0.0 | |
| 21102 | invoke permission denied | 1.0.0 | |
| 20000 | no requestTaskId | 小游戏框架内部错误，有需要请创建工单咨询 | 1.0.0 |
| 20000 | abort | 1.0.0 | |
| 20000 | params $paramName type is not $paramType type | 1.0.0 | |
| 21000 | url is not valid domain, url == $url | 可以包含上一种 | 1.0.0 |
| 20000 | internal error | 小游戏框架内部错误，有需要请创建工单咨询 | 1.0.0 |
| 10501 | app in background | 1.0.0 | |
| 21101 | abort | 1.0.0 | |
| 20000 | url is not valid domain, url == $url | 小游戏框架内部错误，有需要请创建工单咨询 | 1.0.0 |
扫码体验
代码示例
【代码示例 1】：post 请求返回 dataType 为 json 类型的数据，并且可能会中断请求。
let task = tt.request({ url: "someurl", data: { user_name: "hello", }, header: { "content-type": "application/json", }, method: "POST", dataType: "JSON", // 指定返回数据的类型为 json responseType: "text", success(res) { console.log("调用成功", res.data) }, fail(res) { console.log("调用失败", res.errMsg) }, }) // 某些条件下中断请求 if (someReason) { task.abort() }
【代码示例 2】：post 请求返回 dataType 为 string 类型的数据。
tt.request({ url: "someurl", data: { user_name: "hello", }, header: { "content-type": "application/json", }, method: "POST", dataType: "string", // 指定返回数据的类型为 string responseType: "text", success(res) { console.log("调用成功", res.data) }, fail(res) { console.log("调用失败", res.errMsg) }, })
【代码示例 3】：post 请求返回 responseType 为 arraybuffer 类型的数据。
tt.request({ url: "someurl", data: { user_name: "hello", }, header: { "content-type": "application/json", }, method: "POST", dataType: "string", // 在 responseType 为arraybuffer的情况下，不起作用 responseType: "arraybuffer", // 指定返回数据的类型为 arraybuffer success(res) { // 此处返回的res.data类型为 arraybuffer console.log("调用成功", res.data) }, fail(res) { console.log("调用失败", res.errMsg) }, })
【代码示例 4】：post 请求 header['content-type'] 为 application/x-www-form-urlencoded。
tt.request({ url: "someurl", data: { user_name: "hello", }, header: { "content-type": "application/x-www-form-urlencoded", // 此处指定content-type类型 }, method: "POST", dataType: "json", responseType: "text", success(res) { console.log("调用成功", res.data) }, fail(res) { console.log("调用失败", res.errMsg) }, })
【代码示例 5】：post 请求携带 cookie。
const id = "" tt.request({ url: "someurl", data: { user_name: "hello", }, header: { "content-type": "application/json", cookie: "TOUTIAOID" + id, // 此处添加cookie }, method: "POST", dataType: "json", responseType: "text", success(res) { console.log("调用成功", res.data) }, fail(res) { console.log("调用失败", res.errMsg) }, })
【代码示例 6】：put 请求。
tt.request({ url: "someurl", data: { user_name: "hello", }, header: { "content-type": "application/json", }, method: "PUT", // 此处修改请求方法 dataType: "json", responseType: "text", success(res) { console.log("调用成功", res.data) }, fail(res) { console.log("调用失败", res.errMsg) }, })
