Window: fetch() 方法

基线 广泛可用

此功能已经成熟，可以在许多设备和浏览器版本上使用。它自 2017 年 3 月.

报告反馈

fetch() 是 Window 接口的方法，用于开始从网络获取资源的过程，返回一个 promise，该 promise 在响应可用时完成。

该 promise 解析为 Response 对象，表示对请求的响应。

fetch() promise 仅在请求失败时拒绝，例如，由于请求 URL 格式错误或网络错误。fetch() promise 不会 因为服务器响应了指示错误的 HTTP 状态码 (404、504 等) 而拒绝。相反，then() 处理程序必须检查 Response.ok 和/或 Response.status 属性。

fetch() 方法由 内容安全策略 的 connect-src 指令控制，而不是它检索的资源的指令控制。

语法

注意：fetch() 方法的参数与 Request() 构造函数的参数相同。
fetch(resource)
fetch(resource, options)

js

参数

resource

  • 这定义了你想要获取的资源。它可以是
  • 一个字符串或任何具有 字符串化器 的其他对象，包括 URL 对象，它提供你要获取的资源的 URL。该 URL 可以是相对于基 URL 的，基 URL 是窗口上下文中的文档的 baseURI，或工作线程上下文中的 WorkerGlobalScope.location。
一个 Request 对象。

options 可选

一个 RequestInit 对象，包含你要应用于请求的任何自定义设置。

返回值

一个 Promise，解析为 Response 对象。

异常

AbortError DOMException

由于调用了 AbortController 的 abort() 方法，请求被中止。

NotAllowedError DOMException

如果 主题 API 的使用被 browsing-topics 权限策略 特别禁止，并且进行了带有 browsingTopics: true 的 fetch() 请求，则抛出该异常。

TypeError

可能由于以下原因导致 原因
被权限策略阻止 归因报告 API 的使用被 attribution-reporting Permissions-Policy 阻止，并且进行了带有 attributionReporting 指定的 fetch() 请求。
无效的报头名称。 
// space in "C ontent-Type"
const headers = {
  'C ontent-Type': 'text/xml',
  'Breaking-Bad': '<3',
};
fetch('https://example.com/', { headers });
无效的报头值。报头对象必须正好包含两个元素。 
const headers = [
  ['Content-Type', 'text/html', 'extra'],
  ['Accept'],
];
fetch('https://example.com/', { headers });
无效的 URL 或方案，或使用 fetch 不支持的方案，或使用对特定请求模式不支持的方案。 
fetch('blob://example.com/', { mode: 'cors' });
URL 包含凭据。 
fetch('https://user:[email protected]/');
无效的推荐人 URL。 
fetch('https://example.com/', { referrer: './abc\u0000df' });
无效的模式 (navigate 和 websocket)。 
fetch('https://example.com/', { mode: 'navigate' });
如果请求缓存模式是 "only-if-cached" 并且请求模式不是 "same-origin"。 
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors',
});
如果请求方法是无效的名称标记或其中一个禁止的报头 ('CONNECT'、'TRACE' 或 'TRACK')。 
fetch('https://example.com/', { method: 'CONNECT' });
如果请求模式是 "no-cors" 并且请求方法不是 CORS 安全列表中的方法 ('GET'、'HEAD' 或 'POST')。 
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors',
});
如果请求方法是 'GET' 或 'HEAD' 并且主体是非空的或不是 undefined。 
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData(),
});
如果 fetch 抛出网络错误。

示例

在我们的 Fetch 请求示例 中 (见 Fetch 请求实时演示)，我们使用相关的构造函数创建一个新的 Request 对象，然后使用 fetch() 调用来获取它。由于我们正在获取图像，因此我们在响应上运行 Response.blob() 以使其具有正确的 MIME 类型，以便它可以被正确处理，然后创建一个它的对象 URL 并将其显示在 <img> 元素中。

注意：fetch() 方法的参数与 Request() 构造函数的参数相同。
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

window
  .fetch(myRequest)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    return response.blob();
  })
  .then((response) => {
    myImage.src = URL.createObjectURL(response);
  });

在我们的 带有 init 的 Fetch 请求示例 中 (见 Fetch 请求 init 实时演示)，我们执行了相同的操作，只是在调用 fetch() 时传入了一个 options 对象。在这种情况下，我们可以设置一个 Cache-Control 值来指示我们对哪种缓存的响应可以接受

注意：fetch() 方法的参数与 Request() 构造函数的参数相同。
const myImage = document.querySelector("img");
const reqHeaders = new Headers();

// A cached response is okay unless it's more than a week old
reqHeaders.set("Cache-Control", "max-age=604800");

const options = {
  headers: reqHeaders,
};

// Pass init as an "options" object with our headers.
const req = new Request("flowers.jpg", options);

fetch(req).then((response) => {
  // ...
});

你也可以使用 Request 构造函数传入 init 对象以获得相同的效果

注意：fetch() 方法的参数与 Request() 构造函数的参数相同。
const req = new Request("flowers.jpg", options);

你也可以在 init 中使用对象字面量作为 headers

注意：fetch() 方法的参数与 Request() 构造函数的参数相同。
const options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

const req = new Request("flowers.jpg", options);

规范

规范
Fetch 标准
# fetch-method

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参见