Window：fetch() 方法

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

Window 接口的 fetch() 方法用于发起获取资源的请求，它会返回一个会在请求响应后兑现的 promise。

该 promise 会兑现一个表示请求响应的 Response 对象。

当请求失败（例如，因为请求 URL 的格式错误或网络错误）时，fetch() 的 promise 才会被拒绝。fetch() 的 promise 不会因为服务器响应表示错误的 HTTP 状态码（404、504，等）而被拒绝。因此，then() 处理器必须检查 Response.ok 和/或 Response.status 属性。

fetch() 方法由内容安全策略的 connect-src 指令（而不是它查询的资源的指令）控制。

备注： fetch() 方法的参数与 Request() 构造函数是一样的。

语法

js
fetch(resource)
fetch(resource, options)

参数

resource

定义你想要获取的资源。可以是：

  • 一个字符串或任何其他具有字符串化器的对象（包括 URL 对象），提供你想要获取的资源的 URL。URL 可以是相对于基础 URL 的，基础 URL 是窗口上下文中文档的 baseURI 或者 worker 上下文中的 WorkerGlobalScope.location。
  • 一个 Request 对象。
options 可选

一个包含你想要应用到请求上的任何自定义设置的 RequestInit 对象。

返回值

一个 Promise，会兑现 Response 对象。

异常

AbortError DOMException

请求被 AbortController 的 abort() 方法调用所终止。

NotAllowedError DOMException

如果 Topics API 的使用被 browsing-topics 权限策略明确禁止，且 fetch() 请求中包含 browsingTopics: true，则会抛出此异常。

TypeError

可以由以下原因引起：

原因 失败的示例
被权限策略阻止 Attribution Reporting API 的使用被 attribution-reporting Permissions-Policy 所阻止，而 fetch() 请求又指定了 attributionReporting。
无效的标头名称。 
// “C ontent-Type”中的空格
const headers = {
  'C ontent-Type': 'text/xml',
  'Breaking-Bad': '<3',
};
fetch('https://example.com/', { headers });
无效的标头值。标头对象必须明确包含两个元素。 
const headers = [
  ['Content-Type', 'text/html', 'extra'],
  ['Accept'],
];
fetch('https://example.com/', { headers });
无效的 URL 或方案（scheme），或使用 fetch 不支持的方案，或使用不支持特定请求模式的方案。 
fetch('blob://example.com/', { mode: 'cors' });
URL 中包含凭据。 
fetch('https://user:password@example.com/');
无效的来源（referrer）URL。 
fetch('https://example.com/', { referrer: './abc\u0000df' });
无效的模式（navigate 和 websocket）。 
fetch('https://example.com/', { mode: 'navigate' });
如果请求的缓存模式是“only-if-cached”，而请求模式不是“same-origin”。 
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors',
});
如果请求方法是无效的名称标记或被禁止的标头之一（'CONNECT'、'TRACE' 或 'TRACK'）。 
fetch('https://example.com/', { method: 'CONNECT' });
如果请求的模式是“no-cors”，而请求方法不是列入 CORS 白名单的方法（'GET'、'HEAD' 或 'POST'）。 
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors',
});
如果请求方法是 'GET' 或 'HEAD'，而请求体不是 null 或 undefined。 
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData(),
});
如果 fetch 抛出了网络错误。

示例

在 Fetch 请求示例（查看 Fetch 请求在线示例）中，我们使用对应的构造函数创建了一个新的 Request 对象，然后调用 fetch() 获取资源。因为我们是在请求一个图片，为了解析正常，我们对响应执行 Body.blob 来设置相应的 MIME 类型。然后创建一个 Object URL，并在 <img> 元素中把它显示出来。

js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

window
  .fetch(myRequest)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP 错误！状态：${response.status}`);
    }

    return response.blob();
  })
  .then((response) => {
    myImage.src = URL.createObjectURL(response);
  });

在带有初始化的 Fetch 请求示例（查看带有初始化的 Fetch 请求在线示例）中，我们做同样的操作，除了在调用 fetch() 时传入了 options 对象。在本例中，我们可以设置 Cache-Control 值来指示我们可以接受什么类型的缓存响应：

js
const myImage = document.querySelector("img");
const reqHeaders = new Headers();

// 除非缓存的响应超过一周，否则都可以接受
reqHeaders.set("Cache-Control", "max-age=604800");

const options = {
  headers: reqHeaders,
};

// 将带有标头的“options”对象作为 init 来传递。
const req = new Request("flowers.jpg", options);

fetch(req).then((response) => {
  // ...
});

你也可以传入同样的 init 对象到 Request 构造函数，来实现同样的效果：

js
const req = new Request("flowers.jpg", options);

init 对象中的 headers 也可以是一个对象字面量：

js
const options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

const req = new Request("flowers.jpg", options);

规范

Specification
Fetch Standard
# fetch-method

浏览器兼容性

BCD tables only load in the browser

参见