全局函数 fetch()

备注: 此特性在 Web Worker 中可用

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

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

当遇到网络错误(因为权限或其他类似的问题)时,fetch() 返回的 promise 才会被拒绝。fetch() 的 promise 不会因为 HTTP 错误而被拒绝(比如 404504,等)。因此,then() 处理器必须检查 Response.ok 和/或 Response.status 属性。

fetch() 方法由 Content Security Policy (en-US)connect-src 指令控制,而不是它请求的资源。

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

语法

Promise<Response> fetch(input[, init]);

参数

resource

定义你想要获取的资源。这可能是:

  • 一个字符串或任何其他具有 stringifier (en-US) 的对象,包括 URL 对象——提供你想要获取的资源的 URL。
  • 一个 Request 对象。
options 可选

一个包含要应用于请求的自定义设置的对象。可能的选项有:

body

你想要添加到请求中的任意消息主体:可以是一个 BlobArrayBufferTypedArrayDataViewFormDataURLSearchParams、字符串对象或者字符串字面量,或者 ReadableStream 对象。注意 GETHEAD 方法的请求不能包含消息主体。

browsingTopics 实验性

布尔值,表示当前用户选择的主题是否应该在关联请求的 Sec-Browsing-Topics (en-US) 标头中发送。有关更多详细信息,请参阅使用 Topics API (en-US)

cache

字符串,表示请求如何与浏览器的 HTTP 缓存进行交互。可能的值有 defaultno-storereloadno-cacheforce-cacheonly-if-cached,这些取值在 Request 对象的 cache 属性的文档中有记录。

credentials

控制浏览器如何处理凭据(cookieHTTP authentication 条目和 TLS 客户端证书)。必须是以下字符串之一:

  • omit:告诉浏览器在请求中排除凭据,并忽略响应中发送的任何凭据(例如,任何 Set-Cookie 标头)。
  • same-origin:告诉浏览器在请求同源 URL 时包含凭据,并使用来自同源 URL 响应中返回的凭据。这是默认值。
  • include:告诉浏览器在同源和跨源请求中都包含凭据,并始终使用响应中返回的凭据。

    备注: 凭据可以包含在简单和“最终”的跨源请求中,但不应包含在 CORS 预检请求中。

headers

任意你想要附加到请求的标头,可以是 Headers 对象或者带有字符串值的对象字面量。注意有些标头是被禁止的

备注: 请求中可能会有 Authorization HTTP 标头,但是如果请求跨源重定向的话就会被删除。

integrity

包含请求的子资源完整性值(比如 sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=)。

keepalive

keepalive 选项可以允许请求持续保持连接,甚至页面已经关闭的情况。使用 keepalive 标志的 Fetch 是 Navigator.sendBeacon() API 的一种替代方案。

method

请求的方法,比如 "GET""POST",默认值是 "GET"。注意 HEAD 或者 GET 的 Fetch 请求不会设置 Origin 标头(此行为已在 Firefox 65 中修正——参见 Firefox bug 1508661)。不区分大小写的情况下能匹配上 RFC 9110 中的任意字符串都会自动被转成大小。如果你想使用自定义的方法(比如 PATCH),你应该将它变为大写。

mode

你想要使用的模式,比如 corsno-corssame-origin

priority

指定相对于其他同类型的请求的 fetch 请求的优先级。必须是以下字符串之一:

high

相对于其他同类型的请求而言,这是一个高优先级的 fetch 请求。

low

相对于其他同类型的请求而言,这是一个低优先级的 fetch 请求。

auto

自动确定相对于同类型的其他请求的 fetch 请求的优先级(默认)。

redirect

如何处理重定向(redirect)响应:

follow

自动跟随重定向。除非另有说明,否则重定向模式设置为 follow

error

如果发生重定向,则中止并显示错误。

manual

调用者打算在另一个上下文中处理响应。详细信息请参阅 WHATWG fetch 规范

referrer

一个指定请求的引用者的字符串。这可以是同源 URL、about:client 或空字符串。

referrerPolicy

指定请求所使用的 referrer policy。可能是以下其中之一 no-referrerno-referrer-when-downgradesame-originoriginstrict-originorigin-when-cross-originstrict-origin-when-cross-origin 或者 unsafe-url

signal

一个 AbortSignal 对象实例;允许你通过 AbortController 与 fetch 请求进行通信,并在需要时中止请求。

返回值

一个 Promise,resolve 时回传 Response 对象。

例外

类型 描述
AbortError 请求被AbortController.abort()终止。
TypeError Firefox 43 (en-US)开始,如果fetch()接收到含有用户名和密码的 URL(例如http://user:password@example.com),它将会抛出一个TypeError

示例

Fetch Request 示例 (参见 Fetch Request live) 中,我们使用对应的构造器创建了一个新的 Request 对象,然后调用 fetch() 方法获取资源。因为我们是在请求一个图片,为了解析正常,我们对响应执行 Body.blob (en-US) 来设置相应的 MIME 类型。然后创建一个 Object URL,并在 <img> 元素中把它显示出来。

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

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

fetch(myRequest)
  .then(function (response) {
    return response.blob();
  })
  .then(function (response) {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });

Fetch with init then Request 示例 (参见 Fetch Request init live) 中,我们做同样的操作,除了在调用 fetch() 时传入一个 init 对象:

js
var myImage = document.querySelector('img');

var myHeaders = new Headers();
myHeaders.append('Content-Type', 'image/jpeg');

var myInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

var myRequest = new Request('flowers.jpg');

fetch(myRequest,myInit).then(function(response) {
  ...
});

你也可以传入同样的 init 对象到 Request 构造器,来实现同样的效果,如:

js
var myRequest = new Request("flowers.jpg", myInit);

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

js
var myInit = {
  method: "GET",
  headers: {
    "Content-Type": "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

var myRequest = new Request("flowers.jpg", myInit);

规范

Specification
Fetch Standard
# fetch-method

浏览器兼容性

BCD tables only load in the browser

参见