webRequest.onHeadersReceived

browser.webRequest.onHeadersReceived.addListener(
  listener,             // function
  filter,               //  object
  extraInfoSpec         //  optional array of strings
)
browser.webRequest.onHeadersReceived.removeListener(listener)
browser.webRequest.onHeadersReceived.hasListener(listener)

事件有三个函数

addListener(listener, filter, extraInfoSpec)

向此事件添加侦听器。

removeListener(listener)

停止监听此事件。listener 参数是要删除的侦听器。

hasListener(listener)

检查 listener 是否为该事件注册。如果正在监听，则返回 true，否则返回 false。

listener

当此事件发生时调用的函数。该函数将传递以下参数

details

object。请求的详细信息。如果在 extraInfoSpec 中包含了 "responseHeaders"，则将包括响应标头。

返回：webRequest.BlockingResponse。如果在 extraInfoSpec 参数中指定了 "blocking"，则事件侦听器将返回一个 BlockingResponse 对象，并可以设置其 responseHeaders 属性。在 Firefox 中，返回值可以是解析为 BlockingResponse 的 Promise。

filter

webRequest.RequestFilter。一组限制发送到此侦听器的事件的筛选器。

extraInfoSpec 可选

string 的 array。事件的额外选项。您可以传递以下任何值

• "blocking" 以使请求同步，以便您可以修改请求和响应标头
• "responseHeaders" 以将响应标头包含在传递给侦听器的 details 对象中

cookieStoreId

string。如果请求来自在上下文标识中打开的标签，则为上下文标识的 Cookie 存储 ID。有关更多信息，请参阅 使用上下文标识。

documentUrl

string。将在其中加载资源的文档的 URL。例如，如果网页在 "https://example.com" 中包含图像或 iframe，则图像或 iframe 的 documentUrl 将为 "https://example.com"。对于顶级文档，documentUrl 未定义。

frameAncestors

array。有关从请求的文档到顶级文档的框架层次结构中每个文档的信息。数组中的第一个元素包含有关请求文档的直接父级的的信息，最后一个元素包含有关顶级文档的信息。如果加载的是顶级文档，则此数组为空。

url

string。加载文档的 URL。

frameId

integer。文档的 frameId。details.frameAncestors[0].frameId 与 details.parentFrameId 相同。

frameId

integer。如果请求发生在主框架中，则为零；正值是请求发生的子框架的 ID。如果加载了（子）框架的文档（type 为 main_frame 或 sub_frame），则 frameId 表示此框架的 ID，而不是外部框架的 ID。框架 ID 在一个标签内是唯一的。

fromCache

boolean。响应是否从磁盘缓存中获取。

incognito

boolean。请求是否来自私密浏览窗口。

ip

string。发送请求的服务器的 IP 地址。它可以是文字 IPv6 地址。

method

string。标准 HTTP 方法：例如，“GET” 或 “POST”。

originUrl

string。触发请求的资源的 URL。例如，如果 "https://example.com" 包含链接，用户点击了链接，则结果请求的 originUrl 为 "https://example.com"。

originUrl 通常与 documentUrl 相同，但并不总是相同。例如，如果页面包含 iframe，并且 iframe 包含加载新文档到 iframe 的链接，则结果请求的 documentUrl 为 iframe 的父文档，但 originUrl 为包含链接的 iframe 中的文档的 URL。

parentFrameId

integer。包含发送请求的框架的框架的 ID。如果不存在父框架，则设置为 -1。

proxyInfo

object。此属性仅在代理请求时存在。它包含以下属性

host

string。代理服务器的主机名。

port

整数。代理服务器的端口号。

类型

字符串。代理服务器的类型。其中之一

• "http": HTTP 代理（或 HTTPS 的 SSL CONNECT）
• "https": 通过 TLS 连接到代理的 HTTP 代理
• "socks": SOCKS v5 代理
• "socks4": SOCKS v4 代理
• "direct": 无代理
• "unknown": 未知代理

用户名

字符串。代理服务的用户名。

代理DNS

布尔值。如果代理将根据提供的主机名执行域名解析，则为真，这意味着客户端不应执行自己的 DNS 查找。

故障转移超时

整数。故障转移超时（以秒为单位）。如果代理连接失败，则在此期间不会再次使用该代理。

请求 ID

字符串。请求的 ID。请求 ID 在浏览器会话中是唯一的，因此您可以使用它们将与同一请求关联的不同事件关联起来。

responseHeaders 可选

webRequest.HttpHeaders。此请求收到的 HTTP 响应头。

状态码

整数。服务器返回的标准 HTTP 状态码。

状态行

字符串。响应的 HTTP 状态行或 HTTP/0.9 响应（即缺少状态行的响应）的“HTTP/0.9 200 OK”字符串。

标签 ID

整数。发生请求的标签的 ID。如果请求与标签无关，则设置为 -1。

第三方

布尔值。指示请求及其内容窗口层次结构是否为第三方。

时间戳

数字。此事件触发的时刻，以自纪元以来的毫秒数表示。

类型

webRequest.ResourceType。正在请求的资源类型：例如，“image”、“script”、“stylesheet”。

url

字符串。请求的目标。

URL 分类

对象。如果请求被Firefox 跟踪保护分类，则与请求关联的跟踪类型。这是一个具有以下属性的对象

第一方

数组 的 字符串。请求的第一方的分类标志。

第三方

数组 的 字符串。请求或其窗口层次结构的第三方的分类标志。

分类标志包括

• fingerprinting 和 fingerprinting_content：表示请求参与指纹识别（“发现对指纹识别的来源”）。
  • fingerprinting 指示该域属于指纹识别和跟踪类别。此类域的示例包括希望将配置文件与访问用户关联的广告商。
  • fingerprinting_content 指示该域属于指纹识别类别但不属于跟踪类别。此类域的示例包括使用指纹识别技术来识别访问用户以进行反欺诈目的的支付提供商。
• cryptomining 和 cryptomining_content：与指纹识别类别相似，但用于加密挖掘资源。
• tracking、tracking_ad、tracking_analytics、tracking_social 和 tracking_content：表示请求参与跟踪。tracking 是任何通用的跟踪请求，ad、analytics、social 和 content 后缀标识跟踪程序的类型。
• any_basic_tracking：一个元标志，它结合了跟踪和指纹识别标志，不包括 tracking_content 和 fingerprinting_content。
• any_strict_tracking：一个元标志，它结合了所有跟踪和指纹识别标志。
• any_social_tracking：一个元标志，它结合了所有社交跟踪标志。

此代码在从目标 URL 请求资源时设置一个额外的 Cookie

let targetPage =
  "https://mdn.org.cn/en-US/Firefox/Developer_Edition";

// Add the new header to the original array,
// and return it.
function setCookie(e) {
  const setMyCookie = {
    name: "Set-Cookie",
    value: "my-cookie1=my-cookie-value1",
  };
  e.responseHeaders.push(setMyCookie);
  return { responseHeaders: e.responseHeaders };
}

// Listen for onHeaderReceived for the target page.
// Set "blocking" and "responseHeaders".
browser.webRequest.onHeadersReceived.addListener(
  setCookie,
  { urls: [targetPage] },
  ["blocking", "responseHeaders"],
);

此代码与上一个示例的作用相同，只是监听器是异步的，返回一个Promise，该 Promise 通过新的标头解析

const targetPage =
  "https://mdn.org.cn/en-US/Firefox/Developer_Edition";

// Return a Promise that sets a timer.
// When the timer fires, resolve the promise with
// modified set of response headers.
function setCookieAsync(e) {
  const asyncSetCookie = new Promise((resolve, reject) => {
    setTimeout(() => {
      const setMyCookie = {
        name: "Set-Cookie",
        value: "my-cookie1=my-cookie-value1",
      };
      e.responseHeaders.push(setMyCookie);
      resolve({ responseHeaders: e.responseHeaders });
    }, 2000);
  });

  return asyncSetCookie;
}

// Listen for onHeaderReceived for the target page.
// Set "blocking" and "responseHeaders".
browser.webRequest.onHeadersReceived.addListener(
  setCookieAsync,
  { urls: [targetPage] },
  ["blocking", "responseHeaders"],
);