速冻鱼blog

使用 Fetch

8/1/2021 fetch

# 使用 Fetch

Fetch API (opens new window) 提供了一个 JavaScript 接口，用于访问和操纵 HTTP 管道的一些具体部分，例如请求和响应。它还提供了一个全局 fetch() (opens new window) 方法，该方法提供了一种简单，合理的方式来跨网络异步获取资源。

这种功能以前是使用 XMLHttpRequest (opens new window) 实现的。Fetch 提供了一个更理想的替代方案，可以很容易地被其他技术使用，例如 Service Workers (en-US) (opens new window)。Fetch 还提供了专门的逻辑空间来定义其他与 HTTP 相关的概念，例如 CORS 和 HTTP 的扩展。

请注意，fetch 规范与 jQuery.ajax() 主要有三种方式的不同：

  • 当接收到一个代表错误的 HTTP 状态码时，从 fetch() 返回的 Promise 不会被标记为 reject， 即使响应的 HTTP 状态码是 404 或 500。相反，它会将 Promise 状态标记为 resolve （但是会将 resolve 的返回值的 ok 属性设置为 false ），仅当网络故障时或请求被阻止时，才会标记为 reject。
  • fetch() **可以不会接受跨域 cookies；**你也可以不能使用 fetch() 建立起跨域会话。其他网站的 Set-Cookie 头部字段将会被无视。
  • fetch 不会发送 cookies。除非你使用了credentials 的初始化选项 (opens new window)。（自 2017 年 8 月 25 日以后，默认的 credentials 政策变更为 same-origin。Firefox 也在 61.0b13 版本中进行了修改）

一个基本的 fetch 请求设置起来很简单。看看下面的代码：

fetch('http://example.com/movies.json')
  .then(function(response) {
    return response.json();
  })
  .then(function(myJson) {
    console.log(myJson);
  });
1
2
3
4
5
6
7

Copy to Clipboard

这里我们通过网络获取一个 JSON 文件并将其打印到控制台。最简单的用法是只提供一个参数用来指明想 fetch() 到的资源路径，然后返回一个包含响应结果的promise（一个 Response (opens new window) 对象）。

当然它只是一个 HTTP 响应，而不是真的JSON。为了获取JSON的内容，我们需要使用 json() (opens new window) 方法（在 Body (opens new window) mixin 中定义，被 Request (opens new window) 和 Response (opens new window) 对象实现）。

注意：Body mixin 还有其他相似的方法，用于获取其他类型的内容。参考 Body (opens new window)。

最好使用符合内容安全策略 (CSP) (en-US) (opens new window)的链接而不是使用直接指向资源地址的方式来进行Fetch的请求。

# 支持的请求参数 (opens new window)

fetch() 接受第二个可选参数，一个可以控制不同配置的 init 对象：

参考 fetch() (opens new window)，查看所有可选的配置和更多描述。

// Example POST method implementation:

postData('http://example.com/answer', {answer: 42})
  .then(data => console.log(data)) // JSON from `response.json()` call
  .catch(error => console.error(error))

function postData(url, data) {
  // Default options are marked with *
  return fetch(url, {
    body: JSON.stringify(data), // must match 'Content-Type' header
    cache: 'no-cache', // *default, no-cache, reload, force-cache, only-if-cached
    credentials: 'same-origin', // include, same-origin, *omit
    headers: {
      'user-agent': 'Mozilla/4.0 MDN Example',
      'content-type': 'application/json'
    },
    method: 'POST', // *GET, POST, PUT, DELETE, etc.
    mode: 'cors', // no-cors, cors, *same-origin
    redirect: 'follow', // manual, *follow, error
    referrer: 'no-referrer', // *client, no-referrer
  })
  .then(response => response.json()) // parses response to JSON
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Copy to Clipboard

# 发送带凭据的请求 (opens new window)

为了让浏览器发送包含凭据的请求（即使是跨域源），要将credentials: 'include'添加到传递给 fetch()方法的init对象。

fetch('https://example.com', {
  credentials: 'include'
})
1
2
3

Copy to Clipboard

如果你只想在请求URL与调用脚本位于同一起源处时发送凭据，请添加 credentials: 'same-origin'。

// The calling script is on the origin 'https://example.com'

fetch('https://example.com', {
  credentials: 'same-origin'
})
1
2
3
4
5

Copy to Clipboard

要改为确保浏览器不在请求中包含凭据，请使用 credentials: 'omit'。

fetch('https://example.com', {
  credentials: 'omit'
})
1
2
3

Copy to Clipboard

# 上传 JSON 数据 (opens new window)

使用 fetch() (opens new window) POST JSON数据

var url = 'https://example.com/profile';
var data = {username: 'example'};

fetch(url, {
  method: 'POST', // or 'PUT'
  body: JSON.stringify(data), // data can be `string` or {object}!
  headers: new Headers({
    'Content-Type': 'application/json'
  })
}).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(response => console.log('Success:', response));
1
2
3
4
5
6
7
8
9
10
11
12

Copy to Clipboard

# 上传文件 (opens new window)

可以通过 HTML <input type="file" /> 元素，FormData() (opens new window) 和 fetch() (opens new window) 上传文件。

var formData = new FormData();
var fileField = document.querySelector("input[type='file']");

formData.append('username', 'abc123');
formData.append('avatar', fileField.files[0]);

fetch('https://example.com/profile/avatar', {
  method: 'PUT',
  body: formData
})
.then(response => response.json())
.catch(error => console.error('Error:', error))
.then(response => console.log('Success:', response));
1
2
3
4
5
6
7
8
9
10
11
12
13

Copy to Clipboard

# 上传多个文件 (opens new window)

可以通过HTML <input type="file" mutiple/> 元素，FormData() (opens new window) 和 fetch() (opens new window) 上传文件。

var formData = new FormData();
var photos = document.querySelector("input[type='file'][multiple]");

formData.append('title', 'My Vegas Vacation');
// formData 只接受文件、Blob 或字符串，不能直接传递数组，所以必须循环嵌入
for (let i = 0; i < photos.files.length; i++) {
    formData.append('photo', photos.files[i]);
}

fetch('https://example.com/posts', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(response => console.log('Success:', JSON.stringify(response)))
.catch(error => console.error('Error:', error));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Copy to Clipboard

# 检测请求是否成功 (opens new window)

如果遇到网络故障，fetch() (opens new window) promise 将会 reject，带上一个 TypeError (opens new window) 对象。虽然这个情况经常是遇到了权限问题或类似问题——比如 404 不是一个网络故障。想要精确的判断 fetch() 是否成功，需要包含 promise resolved 的情况，此时再判断 Response.ok (opens new window) 是不是为 true。类似以下代码：

fetch('flowers.jpg').then(function(response) {
  if(response.ok) {
    return response.blob();
  }
  throw new Error('Network response was not ok.');
}).then(function(myBlob) {
  var objectURL = URL.createObjectURL(myBlob);
  myImage.src = objectURL;
}).catch(function(error) {
  console.log('There has been a problem with your fetch operation: ', error.message);
});
1
2
3
4
5
6
7
8
9
10
11

Copy to Clipboard

# 自定义请求对象 (opens new window)

除了传给 fetch() 一个资源的地址，你还可以通过使用 Request() (opens new window) 构造函数来创建一个 request 对象，然后再作为参数传给 fetch()：

var myHeaders = new Headers();

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

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

fetch(myRequest).then(function(response) {
  return response.blob();
}).then(function(myBlob) {
  var objectURL = URL.createObjectURL(myBlob);
  myImage.src = objectURL;
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Copy to Clipboard

Request() 和 fetch() 接受同样的参数。你甚至可以传入一个已存在的 request 对象来创造一个拷贝：

var anotherRequest = new Request(myRequest,myInit);
1

Copy to Clipboard

这个很有用，因为 request 和 response bodies 只能被使用一次（译者注：这里的意思是因为设计成了 stream 的方式，所以它们只能被读取一次）。创建一个拷贝就可以再次使用 request/response 了，当然也可以使用不同的 init 参数。

注意：clone() (opens new window) 方法也可以用于创建一个拷贝。它和上述方法一样，如果 request 或 response 的 body 已经被读取过，那么将执行失败。区别在于， clone() 出的 body 被读取不会导致原 body 被标记为已读取。

# Headers (opens new window)

使用 Headers (opens new window) 的接口，你可以通过 Headers() (opens new window) 构造函数来创建一个你自己的 headers 对象。一个 headers 对象是一个简单的多名值对：

var content = "Hello World";
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/plain");
myHeaders.append("Content-Length", content.length.toString());
myHeaders.append("X-Custom-Header", "ProcessThisImmediately");
1
2
3
4
5

Copy to Clipboard

也可以传一个多维数组或者对象字面量：

myHeaders = new Headers({
  "Content-Type": "text/plain",
  "Content-Length": content.length.toString(),
  "X-Custom-Header": "ProcessThisImmediately",
});
1
2
3
4
5

Copy to Clipboard

它的内容可以被获取：

console.log(myHeaders.has("Content-Type")); // true
console.log(myHeaders.has("Set-Cookie")); // false
myHeaders.set("Content-Type", "text/html");
myHeaders.append("X-Custom-Header", "AnotherValue");

console.log(myHeaders.get("Content-Length")); // 11
console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]

myHeaders.delete("X-Custom-Header");
console.log(myHeaders.getAll("X-Custom-Header")); // [ ]
1
2
3
4
5
6
7
8
9
10

Copy to Clipboard

虽然一些操作只能在 ServiceWorkers (en-US) (opens new window) 中使用，但是它提供了更方便的操作 Headers 的 API。

如果使用了一个不合法的HTTP Header属性名，那么Headers的方法通常都抛出 TypeError 异常。如果不小心写入了一个不可写的属性，也会抛出一个 TypeError 异常。除此以外的情况，失败了并不抛出异常。例如：

var myResponse = Response.error();
try {
  myResponse.headers.set("Origin", "http://mybank.com");
} catch(e) {
  console.log("Cannot pretend to be a bank!");
}
1
2
3
4
5
6

Copy to Clipboard

最好在在使用之前检查内容类型 content-type 是否正确，比如：

fetch(myRequest).then(function(response) {
  if(response.headers.get("content-type") === "application/json") {
    return response.json().then(function(json) {
      // process your JSON further
    });
  } else {
    console.log("Oops, we haven't got JSON!");
  }
});
1
2
3
4
5
6
7
8
9

Copy to Clipboard

# Guard (opens new window)

由于 Headers 可以在 request 请求中被发送或者在 response 请求中被接收，并且规定了哪些参数是可写的，Headers 对象有一个特殊的 guard 属性。这个属性没有暴露给 Web，但是它影响到哪些内容可以在 Headers 对象中被操作。

可能的值如下：

注意：你不可以添加或者修改一个 guard 属性是 request 的 Request Header 的 Content-Length 属性。同样地，插入 Set-Cookie 属性到一个 response header 是不允许的，因此，Service Worker 中，不能给合成的 Response 的 header 添加一些 cookie。

# Response 对象 (opens new window)

如上所述，Response (opens new window) 实例是在 fetch() 处理完 promise 之后返回的。

你会用到的最常见的 response 属性有:

它的实例也可用通过 JavaScript 来创建，但只有在 ServiceWorkers (en-US) (opens new window) 中才真正有用，当使用 respondWith() (opens new window) 方法并提供了一个自定义的 response 来接受 request 时：

var myBody = new Blob();

addEventListener('fetch', function(event) {
  event.respondWith(new Response(myBody, {
    headers: { "Content-Type" : "text/plain" }
  });
});
1
2
3
4
5
6
7

Copy to Clipboard

Response() (opens new window) 构造方法接受两个可选参数—— response 的数据体和一个初始化对象（与Request() (opens new window) 所接受的 init 参数类似。）

注意: 静态方法 error() (opens new window) 只是返回了错误的response。与此类似地，redirect() (opens new window) 只是返回了一个可以重定向至某 URL 的 response。这些也只与 Service Worker 有关。

# Body (opens new window)

不管是请求还是响应都能够包含 body 对象。body 也可以是以下任意类型的实例。

Body (opens new window) 类定义了以下方法（这些方法都被 Request (opens new window) 和Response (opens new window)所实现）以获取 body 内容。这些方法都会返回一个被解析后的Promise (en-US) (opens new window)对象和数据。

比起XHR来，这些方法让非文本化的数据使用起来更加简单。

请求体可以由传入 body 参数来进行设置：

var form = new FormData(document.getElementById('login-form'));
fetch("/login", {
  method: "POST",
  body: form
})
1
2
3
4
5

Copy to Clipboard

request和response（包括 fetch() 方法）都会试着自动设置 Content-Type。如果没有设置 Content-Type 值，发送的请求也会自动设值。

# 特性检测 (opens new window)

Fetch API 的支持情况，可以通过检测Headers (opens new window), Request (opens new window), Response (opens new window) 或 fetch() (opens new window)是否在Window (opens new window) 或 Worker (opens new window) 域中。例如：

if(self.fetch) {
    // run my fetch request here
} else {
    // do something with XMLHttpRequest?
}
1
2
3
4
5

Copy to Clipboard

# Polyfill (opens new window)

如果要在不支持的浏览器中使用 Fetch，可以使用 Fetch Polyfill (opens new window)。

# 规范 (opens new window)

详细说明 状态 注释
Fetch (opens new window) Living Standard Initial definition

# 浏览器兼容性 (opens new window)

[Report problems with this compatibility data on GitHub](https://github.com/mdn/browser-compat-data/issues/new?body= %23%23%23%23+What+information+was+incorrect%2C+unhelpful%2C+or+incomplete%3F %23%23%23%23+What+did+you+expect+to+see%3F %23%23%23%23+Did+you+test+this%3F+If+so%2C+how%3F MDN+page+report+details<%2Fsummary> *+Query%3A+api.WindowOrWorkerGlobalScope.fetch *+MDN+URL%3A+https%3A%2F%2Fdeveloper.mozilla.org%2Fzh-CN%2Fdocs%2FWeb%2FAPI%2FFetch_API%2FUsing_Fetch *+Report+started%3A+2021-07-19T02%3A40%3A10.801Z <%2Fdetails>&title=api.WindowOrWorkerGlobalScope.fetch+-+)

desktop mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet
fetchExperimental Full support42 Full support14 Full support39 No supportNo Full support29 Full support10.1 Full support42 Full support42 Full support39 Full support29 Full support10.3 Full support4.0
Support for blob: and data:Experimental Full support48 Full support79 Compatibility unknown; please update this.? No supportNo Compatibility unknown; please update this.? Compatibility unknown; please update this.? Full support43 Full support48 Compatibility unknown; please update this.? Compatibility unknown; please update this.? Compatibility unknown; please update this.? Full support5.0
referrerPolicy Full support52 Full support79 Full support52 No supportNo Full support39 Full support11.1 Full support52 Full support52 Full support52 Full support41 No supportNo Full support6.0
signalExperimental Full support66 Full support16 Full support57 No supportNo Full support53 Full support11.1 Full support66 Full support66 Full support57 Full support47 Full support11.3 Full support9.0
Streaming response bodyExperimental Full support43 Full support14 Full supportYesdisabledOpen No supportNo Full support29 Full support10.1 Full support43 Full support43 No supportNo No supportNo Full support10.3 Full support4.0

# Legend

# 参见 (opens new window)

Last Updated: 8/1/2021, 5:24:42 PM