fetch()
fetch() 函数发出一个 HTTP 请求,返回一个 Promise。服务器的状态码、响应头和第一块响应内容到达时,这个 Promise 完成,得到一个 Response。
请求在后台进行。等待期间 JS 继续执行,界面照常响应。请求不依赖界面,App 启动后在任何地方都可以发,包括文件顶层,不用等 sceneconnect。fetch() 可以请求任何服务器,不受跨域规则限制。
和 fetch() 一起使用的几个类:
Response:一次请求得到的响应,读状态码、响应头和响应内容。Request:把一次请求的地址和选项保存成一个对象。Blob:一块不可修改的二进制数据,用来上传和保存下载的内容。ReadableStream和ReadableStreamDefaultReader:一块一块地读还在下载的响应内容。AbortController和AbortSignal:取消请求、给请求设超时。Headers和URL:请求头和地址。
怎么用这些类完成常见的任务,见指南从网络取数据和边下载边读响应。
函数
发出一个请求,返回 Promise,完成时得到 Response。
示例
下面的代码请求一个返回 JSON 的地址,把结果输出到控制台。整段可以直接写在 main.js 的顶层。
js
async function load() {
// 1. 发请求。响应头和第一块内容到达时这一行就返回了
const res = await fetch('https://httpbin.org/get');
// 2. 检查服务器是否返回了成功的状态
if (!res.ok) {
console.log('服务器返回了错误:', res.status);
return;
}
// 3. 读出响应内容,按 JSON 解析
const data = await res.json();
console.log(res.status, data.url);
}
// 4. 网络不通时 fetch 会失败,要接住
load().catch((err) => {
console.log('请求没有发出去或没有收到响应:', err.message);
});结果
- 网络正常时,控制台输出
200 https://httpbin.org/get。 - 服务器返回 404 或 500 时,输出
服务器返回了错误: 404。 - 没有网络或连不上服务器时,输出
请求没有发出去或没有收到响应:加一段错误说明。
第 2 步和第 4 步处理的是两种不同的失败,见请求什么时候算失败。
注意:
await只能写在async函数里。文件顶层不能直接写await。
和 Web 的差别
fetch 这一组接口的名字和 Web 的相同。差别逐条写在各成员页的「和 Web 的差别」里,这张表汇总在一起,给熟悉 Web 写法的人查。
| Web | Nacre |
|---|---|
await fetch(url, init) | 相同。url 必须是完整地址 |
fetch() 在响应头到达时完成 | 在第一块响应内容到达时完成 |
init.body 可以是字符串、Blob、ArrayBuffer、类型数组、URLSearchParams | 相同 |
init.body 可以是 FormData、ReadableStream | 没有 |
body 是 ArrayBuffer 且没写 Content-Type 时,不发这个请求头 | 系统会填上 application/x-www-form-urlencoded |
init.mode、init.credentials、init.cache、init.redirect | 没有,写了不起作用 |
| CORS 预检、同源策略 | 没有,可以请求任何地址 |
不允许设置 Host、Cookie 等请求头 | 都可以设置 |
取消时抛出 signal.reason,默认是 DOMException | 抛出 name 为 'AbortError' 的 Error。没有 DOMException 这个类 |
AbortSignal.timeout() 到时间后 fetch() 抛出 TimeoutError | 抛出 AbortError |
res.statusText | fetch() 得到的响应上永远是空串 |
res.text() 按响应声明的编码解码,不合法的字节换成替换字符 | 一律按 UTF-8 解码,不合法时得到空串 |
res.blob() 的 type 取自 Content-Type | type 是空串 |
res.formData()、res.clone() | 没有 |
req.body | 没有。Request 的内容只能用四个读取方法读 |
new Blob([blob]) | 抛 TypeError |
read() 在请求被取消时以 signal.reason 拒绝 | 以 AbortError 拒绝 |
reader.closed 在内容到头时完成 | 来自 fetch() 的流要 read() 到 done 才完成 |
| 没有读内容时也限制缓冲,下载会停下来等 | 开始用 read() 读之后才限制,之前一直下载 |
没有 Content-Length 的响应被截断时报错 | 服务器正常关闭连接时不报错 |
new ReadableStream(…)、pipeTo()、pipeThrough()、tee()、getReader({ mode: 'byob' }) | 没有 |
WritableStream、TransformStream、EventSource | 没有 |