RequestInit

RequestInitFetch API 中的一个字典,表示用于配置 Fetch 请求的一组选项。

您可以将 RequestInit 对象传递给 Request() 构造函数,或直接传递给 fetch() 函数调用。

您还可以使用 RequestInit 构造一个 Request,并将 Request 以及另一个 RequestInit 传递给 fetch() 调用。如果您这样做,并且在两个地方都设置了相同的选项,则直接传递给 fetch() 的值将被使用。

实例属性

attributionReporting 可选 实验性

指示您希望请求的响应能够注册基于 JavaScript 的 归因来源归因触发器attributionReporting 是一个包含以下属性的对象

eventSourceEligible

布尔值。如果设置为 true,则请求的响应有资格注册归因来源。如果设置为 false,则没有资格。

triggerEligible

布尔值。如果设置为 true,则请求的响应有资格注册归因触发器。如果设置为 false,则没有资格。

有关更多详细信息,请参阅 归因报告 API

body 可选

请求主体包含要发送到服务器的内容,例如在 POSTPUT 请求中。它被指定为以下任何类型的一个实例

有关更多详细信息,请参阅 设置主体

browsingTopics 可选 实验性

一个布尔值,指定是否应在与关联请求的 Sec-Browsing-Topics 标头中发送当前用户的选定主题。

有关更多详细信息,请参阅 使用主题 API

cache 可选

您希望用于请求的 缓存模式。这可以是以下任何一个值

default

浏览器会在其 HTTP 缓存中查找与请求匹配的响应。

  • 如果存在匹配项并且它是 新鲜的,则它将从缓存中返回。
  • 如果存在匹配项但它是 陈旧的,则浏览器将向远程服务器发出 条件请求。如果服务器指示资源未更改,则它将从缓存中返回。否则,资源将从服务器下载,并且缓存将更新。
  • 如果没有匹配项,浏览器将发出普通请求,并使用下载的资源更新缓存。
no-store

浏览器从远程服务器获取资源,而不会先查看缓存,并且不会使用下载的资源更新缓存。

reload

浏览器从远程服务器获取资源,而不会先查看缓存,但随后会使用下载的资源更新缓存。

no-cache

浏览器会在其 HTTP 缓存中查找与请求匹配的响应。

  • 如果存在匹配项,无论新鲜还是陈旧,浏览器都将向远程服务器发出 条件请求。如果服务器指示资源未更改,则它将从缓存中返回。否则,资源将从服务器下载,并且缓存将更新。
  • 如果没有匹配项,浏览器将发出普通请求,并使用下载的资源更新缓存。
force-cache

浏览器会在其 HTTP 缓存中查找与请求匹配的响应。

  • 如果存在匹配项,无论新鲜还是陈旧,它将从缓存中返回。
  • 如果没有匹配项,浏览器将发出普通请求,并使用下载的资源更新缓存。
only-if-cached

浏览器会在其 HTTP 缓存中查找与请求匹配的响应。 实验性

  • 如果存在匹配项,无论新鲜还是陈旧,它将从缓存中返回。
  • 如果没有匹配项,则返回网络错误。

只有当请求的 mode"same-origin" 时,才能使用 "only-if-cached" 模式。如果请求的 redirect 属性为 "follow" 并且重定向不违反 "same-origin" 模式,则将遵循缓存的重定向。

credentials 可选

控制浏览器是否随请求发送凭据,以及是否尊重任何 Set-Cookie 响应标头。凭据是 Cookie、TLS 客户端证书或包含用户名和密码的身份验证标头。此选项可以是以下任何一个值

omit

从不发送请求中的凭据或在响应中包含凭据。

same-origin

仅为同源请求发送和包含凭据。

include

始终包含凭据,即使对于跨源请求也是如此。

在跨源请求中包含凭据可能会使站点容易受到 CSRF 攻击,因此即使 credentials 设置为 include,服务器也必须通过在其响应中包含 Access-Control-Allow-Credentials 来同意其包含。此外,在这种情况下,服务器必须在 Access-Control-Allow-Origin 响应标头中明确指定客户端的来源(即,不允许使用 *)。

有关更多详细信息,请参阅 包含凭据

默认为 same-origin

headers 可选

您想要添加到请求的任何标头,包含在 Headers 对象或对象文字中,其键是标头名称,其值是标头值。

许多标头由浏览器自动设置,脚本无法设置:这些称为 禁止的标头名称

如果 mode 选项设置为 no-cors,则您只能设置 CORS 安全列表请求标头

有关更多详细信息,请参阅 设置标头

integrity

包含请求的 子资源完整性 值。

这将在获取资源时进行检查,就像在 integrity 属性设置为 <script> 元素时一样。浏览器将使用指定的算法计算获取资源的 哈希值,如果结果与指定的值不匹配,则浏览器将拒绝获取请求并返回网络错误。

此选项的格式为 <hash-algo>-<hash-source>,其中

  • <hash-algo> 是以下值之一:sha256sha384sha512
  • <hash-source> 是使用指定的哈希算法对资源进行哈希处理的结果的 Base64 编码

默认为空字符串。

keepalive 可选

布尔值。如果为 true,则即使在请求完成之前卸载了发出请求的页面,浏览器也不会中止请求。这使 Fetch 请求能够在会话结束时发送分析时,作为 Navigator.sendBeacon() 的替代方案。

保持活动请求的主体大小限制为 64 千字节。

默认为 false

method 可选

请求方法

默认为 GET

mode 可选

以下值之一

same-origin

完全禁止跨源请求。

cors

如果请求是跨源请求,则它将使用 跨源资源共享 (CORS) 机制。

no-cors

请求必须是 简单请求,这会将可以设置的标头限制为 CORS 安全列表请求标头,并将方法限制为 GETHEADPOST

仅由 HTML 导航使用。仅在文档之间导航时才会创建 navigate 请求。

websocket

仅在建立 WebSocket 连接时使用。

有关更多详细信息,请参阅 发出跨源请求

默认为 cors

priority 可选

指定相对于同一类型其他请求的获取请求的优先级。必须是以下之一

high

相对于同一类型其他请求的高优先级获取请求。

low

相对于同一类型其他请求的低优先级获取请求。

auto

自动确定相对于同一类型其他请求的获取请求的优先级。

默认为 auto

redirect 可选

确定服务器返回重定向状态时浏览器的行为。以下值之一

follow

自动跟随重定向。

error

当返回重定向状态时,使用网络错误拒绝 Promise。

manual

返回一个几乎所有字段都被过滤掉的响应,以使服务工作线程能够存储响应并在以后重播它。

默认为 follow

referrer 可选

一个字符串,指定用于请求的Referer标头的值。以下之一

同源的相对或绝对 URL

Referer 标头设置为给定值。相对 URL 相对于发出请求的页面的 URL 解析。

空字符串

省略 Referer 标头。

about:client

Referer 标头设置为请求上下文的默认值(例如,发出请求的页面的 URL)。

默认为 about:client

referrerPolicy 可选

一个字符串,用于设置Referer标头的策略。此选项的语法和语义与Referrer-Policy标头完全相同。

signal 可选

一个AbortSignal。如果设置了此选项,则可以通过在相应的 AbortController 上调用abort()来取消请求。

示例

将选项传递到 fetch()

在此示例中,我们将 methodbodyheaders 选项直接传递到fetch() 方法调用中

js
async function post() {
  const response = await fetch("https://example.org/post", {
    method: "POST",
    body: JSON.stringify({ username: "example" }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  console.log(response.status);
}

将选项传递到 Request() 构造函数

在此示例中,我们创建了一个Request,将同一组选项传递到其构造函数中,然后将请求传递到 fetch()

js
async function post() {
  const request = new Request("https://example.org/post", {
    method: "POST",
    body: JSON.stringify({ username: "example" }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  const response = await fetch(request);

  console.log(response.status);
}

将选项传递到 Request()fetch()

在此示例中,我们创建了一个Request,将 methodheadersbody 选项传递到其构造函数中。然后,我们将请求与 bodyreferrer 选项一起传递到 fetch()

js
async function post() {
  const request = new Request("https://example.org/post", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ username: "example1" }),
  });

  const response = await fetch(request, {
    body: JSON.stringify({ username: "example2" }),
    referrer: "",
  });

  console.log(response.status);
}

在这种情况下,请求将使用以下选项发送

  • method: "POST"
  • headers: {"Content-Type": "application/json"}
  • body: '{"username":"example2"}'
  • referrer: ""

规范

规范
获取标准
# requestinit

另请参阅