Fetch API

1,007 阅读7分钟

「这是我参与11月更文挑战的第13天,活动详情查看:2021最后一次更文挑战」。

Fetch API

Fetch API 能够执行 XMLHttpRequest 对象的所有任务,但更容易使用,接口也更现代化,能够在 Web 工作线程等现代 Web 工具中使用。XMLHttpRequest 可以选择异步,而 Fetch API 则必须是异步。

Fetch API 是 WHATWG 的一个“活标准”(living standard),用规范原文说,就是“Fetch 标准定义请求、 响应,以及绑定二者的流程:获取(fetch)”。 Fetch API 本身是使用 JavaScript 请求资源的优秀工具,同时这个 API 也能够应用在服务线程 (service worker)中,提供拦截、重定向和修改通过 fetch()生成的请求接口。

基本用法

fetch()方法是暴露在全局作用域中的,包括主页面执行线程、模块和工作线程。调用这个方法, 浏览器就会向给定 URL 发送请求。

  1. 分派请求 fetch()只有一个必需的参数 input。多数情况下,这个参数是要获取资源的 URL。这个方法返回 一个期约:
let r = fetch('/bar'); 
console.log(r); // Promise 

URL 的格式(相对路径、绝对路径等)的解释与 XHR 对象一样。

请求完成、资源可用时,期约会解决为一个 Response 对象。这个对象是 API 的封装,可以通过它 取得相应资源。获取资源要使用这个对象的属性和方法,掌握响应的情况并将负载转换为有用的形式, 如下所示:

fetch('bar.txt') 
    .then((response) => { 
        console.log(response); 
    });
  1. 读取响应 读取响应内容的最简单方式是取得纯文本格式的内容,这要用到 text()方法。这个方法返回一个 期约,会解决为取得资源的完整内容:
fetch('bar.txt') 
    .then((response) => { 
        response.text().then((data) => { 
            console.log(data); 
        }); 
    }); 
  1. 自定义选项 只使用 URL 时,fetch()会发送 GET 请求,只包含最低限度的请求头。要进一步配置如何发送请 求,需要传入可选的第二个参数 init 对象。init 对象要按照下表中的键/值进行填充。
body指定使用请求体时请求体的内容 必须是 Blob、BufferSource、FormData、URLSearchParams、ReadableStream 或 String 的 实例
cache用于控制浏览器与 HTTP缓存的交互。要跟踪缓存的重定向,请求的 redirect 属性值必须是"follow", 而且必须符合同源策略限制。必须是下列值之一
Default
1 fetch()返回命中的有效缓存。不发送请求;
2 命中无效(stale)缓存会发送条件式请求。如果响应已经改变,则更新缓存的值。然后 fetch() 返回缓存的值
no-store
1 浏览器不检查缓存,直接发送请求
2 不缓存响应,直接通过 fetch()返回
reload
1浏览器不检查缓存,直接发送请求
2 缓存响应,再通过 fetch()返回
no-cache
1 无论命中有效缓存还是无效缓存都会发送条件式请求。如果响应已经改变,则更新缓存的值。然 后 fetch()返回缓存的值
2 未命中缓存会发送请求,并缓存响应。然后 fetch()返回响应
force-cache
1 无论命中有效缓存还是无效缓存都通过 fetch()返回。不发送请求
2 未命中缓存会发送请求,并缓存响应。然后 fetch()返回响应
only-if-cached
1 只在请求模式为 same-origin 时使用缓存
2 无论命中有效缓存还是无效缓存都通过 fetch()返回。不发送请求
3 未命中缓存返回状态码为 504(网关超时)的响应 默认为 default
credentials用于指定在外发请求中如何包含 cookie。与 XMLHttpRequest 的 withCredentials 标签类似 必须是下列字符串值之一
1 omit:不发送 cookie
2 same-origin:只在请求 URL 与发送 fetch()请求的页面同源时发送 cookie
3 include:无论同源还是跨源都包含 cookie
在支持 Credential Management API 的浏览器中,也可以是一个 FederatedCredential 或 PasswordCredential 的实例 默认为 same-origin
headers用于指定请求头部
必须是 Headers 对象实例或包含字符串格式键/值对的常规对象
默认值为不包含键/值对的 Headers 对象。这不意味着请求不包含任何头部,浏览器仍然会随请求 发送一些头部。虽然这些头部对 JavaScript 不可见,但浏览器的网络检查器可以观察到
integrity用于强制子资源完整性
必须是包含子资源完整性标识符的字符串
默认为空字符串
keepalive用于指示浏览器允许请求存在时间超出页面生命周期。适合报告事件或分析,比如页面在 fetch() 请求后很快卸载。设置 keepalive 标志的 fetch()请求可用于替代 Navigator.sendBeacon()
必须是布尔值
默认为 false
method用于指定 HTTP 请求方法
基本上就是如下字符串值:
GET
POST
PUT
PATCH
DELETE
HEAD
OPTIONS
CONNECT
TARCE
默认为 GET
mode用于指定请求模式。这个模式决定来自跨源请求的响应是否有效,以及客户端可以读取多少响应。 违反这里指定模式的请求会抛出错误
必须是下列字符串值之一
cors:允许遵守 CORS 协议的跨源请求。响应是“CORS 过滤的响应”,意思是响应中可以访问 的浏览器头部是经过浏览器强制白名单过滤的
no-cors:允许不需要发送预检请求的跨源请求(HEAD、GET 和只带有满足 CORS 请求头部的 POST)。响应类型是 opaque,意思是不能读取响应内容
same-origin:任何跨源请求都不允许发送
navigate:用于支持 HTML 导航,只在文档间导航时使用。基本用不到
在通过构造函数手动创建 Request 实例时,默认为 cors;否则,默认为 no-cors
redirect用于指定如何处理重定向响应(状态码为 301、302、303、307 或 308) <br必须是下列字符串值之一
follow:跟踪重定向请求,以最终非重定向 URL 的响应作为最终响应
error:重定向请求会抛出错误
manual:不跟踪重定向请求,而是返回 opaqueredirect 类型的响应,同时仍然暴露期望的重 定向 URL。允许以手动方式跟踪重定向
默认为 follow
referrer用于指定 HTTP 的 Referer 头部的内容
必须是下列字符串值之一
no-referrer:以 no-referrer 作为值
client/about:client:以当前 URL 或 no-referrer(取决于来源策略 referrerPolicy)作 为值
URL以伪造 URL 作为值。伪造 URL 的源必须与执行脚本的源匹配
默认为 client/about:client
referrerPolicy用于指定 HTTP 的 Referer 头部
必须是下列字符串值之一
no-referrer
请求中不包含 Referer 头部
no-referrer-when-downgrade
对于从安全 HTTPS 上下文发送到 HTTP URL 的请求,不包含 Referer 头部
对于所有其他请求,将 Referer 设置为完整 URL
origin
对于所有请求,将 Referer 设置为只包含源
same-origin
对于跨源请求,不包含 Referer 头部
对于同源请求,将 Referer 设置为完整 URL
strict-origin
对于从安全 HTTPS 上下文发送到 HTTP URL 的请求,不包含 Referer 头部
对于所有其他请求,将 Referer 设置为只包含源
origin-when-cross-origin
对于跨源请求,将 Referer 设置为只包含源  对于同源请求,将 Referer 设置为完整 URL
strict-origin-when-cross-origin
对于从安全 HTTPS 上下文发送到 HTTP URL 的请求,不包含 Referer 头部
对于所有其他跨源请求,将 Referer 设置为只包含源  对于同源请求,将 Referer 设置为完整 URL
unsafe-url
对于所有请求,将 Referer 设置为完整 URL
默认为 no-referrer-when-downgrade
signal用于支持通过 AbortController 中断进行中的 fetch()请求
必须是 AbortSignal 的实例
默认为未关联控制器的 AbortSignal 实例