Skip to content

fetch() ​

fetch() 函数发出一个 HTTP 请求,返回一个 Promise。服务器的状态码、响应头和第一块响应内容到达时,这个 Promise 完成,得到一个 Response。

请求在后台进行。等待期间 JS 继续执行,界面照常响应。请求不依赖界面,App 启动后在任何地方都可以发,包括文件顶层,不用等 sceneconnect。fetch() 可以请求任何服务器,不受跨域规则限制。

和 fetch() 一起使用的几个类:

怎么用这些类完成常见的任务,见指南从网络取数据和边下载边读响应。

函数 ​

fetch()

发出一个请求,返回 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 写法的人查。

WebNacre
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.statusTextfetch() 得到的响应上永远是空串
res.text() 按响应声明的编码解码,不合法的字节换成替换字符一律按 UTF-8 解码,不合法时得到空串
res.blob() 的 type 取自 Content-Typetype 是空串
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没有

参见 ​