全局函数 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.
备注: 此特性在 Web Worker 中可用。
全局 fetch()
方法用于发起获取资源的请求,它会返回一个会在请求响应后兑现的 promise。
该 promise 会兑现一个表示请求响应的 Response
对象。
当遇到网络错误(因为权限或其他类似的问题)时,fetch()
返回的 promise 才会被拒绝。fetch()
的 promise 不会因为 HTTP 错误而被拒绝(比如 404
、504
,等)。因此,then()
处理器必须检查 Response.ok
和/或 Response.status
属性。
fetch()
方法由 Content Security Policy 的 connect-src
指令控制,而不是它请求的资源。
备注: fetch()
方法的参数与 Request()
构造器是一样的。
语法
Promise<Response> fetch(input[, init]);
参数
resource
-
定义你想要获取的资源。这可能是:
- 一个字符串或任何其他具有 stringifier 的对象,包括
URL
对象——提供你想要获取的资源的 URL。 - 一个
Request
对象。
- 一个字符串或任何其他具有 stringifier 的对象,包括
options
可选-
一个包含要应用于请求的自定义设置的对象。可能的选项有:
body
-
你想要添加到请求中的任意消息主体:可以是一个
Blob
、ArrayBuffer
、TypedArray
、DataView
、FormData
、URLSearchParams
、字符串对象或者字符串字面量,或者ReadableStream
对象。注意GET
或HEAD
方法的请求不能包含消息主体。 browsingTopics
实验性-
布尔值,表示当前用户选择的主题是否应该在关联请求的
Sec-Browsing-Topics
标头中发送。有关更多详细信息,请参阅使用 Topics API。 cache
-
字符串,表示请求如何与浏览器的 HTTP 缓存进行交互。可能的值有
default
、no-store
、reload
、no-cache
、force-cache
和only-if-cached
,这些取值在Request
对象的cache
属性的文档中有记录。 credentials
-
控制浏览器如何处理凭据(cookie、HTTP 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
-
你想要使用的模式,比如
cors
、no-cors
或same-origin
。 priority
-
指定相对于其他同类型的请求的 fetch 请求的优先级。必须是以下字符串之一:
redirect
-
如何处理重定向(
redirect
)响应:follow
-
自动跟随重定向。除非另有说明,否则重定向模式设置为
follow
。 error
-
如果发生重定向,则中止并显示错误。
manual
-
调用者打算在另一个上下文中处理响应。详细信息请参阅 WHATWG fetch 规范。
referrer
-
一个指定请求的引用者的字符串。这可以是同源 URL、
about:client
或空字符串。 referrerPolicy
-
指定请求所使用的 referrer policy。可能是以下其中之一
no-referrer
、no-referrer-when-downgrade
、same-origin
、origin
、strict-origin
、origin-when-cross-origin
、strict-origin-when-cross-origin
或者unsafe-url
。 signal
-
一个
AbortSignal
对象实例;允许你通过AbortController
与 fetch 请求进行通信,并在需要时中止请求。
返回值
例外
类型 | 描述 |
---|---|
AbortError |
请求被AbortController.abort() 终止。 |
TypeError |
从Firefox 43开始,如果fetch() 接收到含有用户名和密码的 URL(例如http://user:password@example.com ),它将会抛出一个TypeError 。 |
示例
在 Fetch Request 示例 (参见 Fetch Request live) 中,我们使用对应的构造器创建了一个新的 Request
对象,然后调用 fetch() 方法获取资源。因为我们是在请求一个图片,为了解析正常,我们对响应执行 Body.blob
来设置相应的 MIME 类型。然后创建一个 Object URL,并在 <img>
元素中把它显示出来。
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 对象:
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 构造器,来实现同样的效果,如:
var myRequest = new Request("flowers.jpg", myInit);
init
对象中的 headers
也可以是一个对象字面量:
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