fetch()
全局的 fetch()
方法用于发起获取资源的请求。它返回一个 promise,这个 promise 会在请求响应后被 resolve,并传回 Response
对象。
Window
和 WorkerGlobalScope
(en-US) 都实现了 WorkerOrGlobalScope。 ——这意味着基本在任何场景下只要你想获取资源,都可以使用 位于 WorkerOrGlobalScope 中的 fetch()
方法。
当遇到网络错误时,fetch()
返回的 promise 会被 reject,并传回 TypeError
,虽然这也可能因为权限或其他问题导致。成功的 fetch() 检查不仅要包括 promise 被 resolve,还要包括 Response.ok
属性为 true。HTTP 404 状态并不被认为是网络错误。
fetch()
方法由 Content Security Policy (en-US) 的 connect-src
指令控制,而不是它请求的资源。
语法
Promise<Response> fetch(input[, init]);
参数
- ?input
-
定义要获取的资源。这可能是:
- init 可选
-
一个配置项对象,包括所有对请求的设置。可选的参数有:
method
: 请求使用的方法,如GET
、POST
。headers
: 请求的头信息,形式为Headers
的对象或包含ByteString
值的对象字面量。body
: 请求的 body 信息:可能是一个Blob
、BufferSource
、FormData
、URLSearchParams
或者USVString
对象。注意 GET 或 HEAD 方法的请求不能包含 body 信息。mode
: 请求的模式,如cors
、no-cors
或者same-origin
。credentials
: 请求的 credentials,如omit
、same-origin
或者include
。为了在当前域名内自动发送 cookie,必须提供这个选项,从 Chrome 50 开始,这个属性也可以接受FederatedCredential
(en-US) 实例或是一个PasswordCredential
(en-US) 实例。cache
: 请求的 cache 模式:default
、no-store
、reload
、no-cache
、force-cache
或者only-if-cached
。redirect
: 可用的 redirect 模式:follow
(自动重定向),error
(如果产生重定向将自动终止并且抛出一个错误),或者manual
(手动处理重定向)。在 Chrome 中默认使用follow
(Chrome 47 之前的默认值是manual
)。referrer
: 一个USVString
可以是no-referrer
、client
或一个 URL。默认是client
。referrerPolicy
: 指定了 HTTP 头部 referer 字段的值。可能为以下值之一:no-referrer
、no-referrer-when-downgrade
、origin
、origin-when-cross-origin
、unsafe-url
。integrity
: 包括请求的 subresource integrity 值(例如:sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=
)。
返回值
例外
类型 | 描述 |
---|---|
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