webRequest.filterResponseData()

使用此函数为请求创建 webRequest.StreamFilter 对象。流过滤器使 Web 扩展可以完全控制流,并能够监控和修改响应。扩展负责写入、关闭或断开连接流,因为默认行为是保持请求打开,不进行响应。

通常从 webRequest 事件监听器调用此函数。

Firefox 为脚本请求使用优化的字节缓存。此优化的字节缓存会覆盖正常的请求缓存。此缓存中的数据无法以对扩展有用的形式获取。如果您的扩展需要筛选脚本,请在 webRequest.onBeforeRequest 中创建过滤器。这样做可以确保在尝试从缓存加载之前创建过滤器,从而避免优化缓存。

权限

要使用此 API,您必须具有 "webRequest""webRequestBlocking" API 权限,以及事件监听器的主机权限,用于指定主机。此外

  • 从 Firefox 95 开始,要使用此 API 拦截与加载服务工作者脚本相关的请求,还需要 "webRequestFilterResponse.serviceWorkerScript" 权限。
  • 从 Firefox 110 开始,清单 V3 扩展还需要请求 "webRequestFilterResponse" 权限才能使用此 API。

语法

js
let filter = browser.webRequest.filterResponseData(
  requestId       // string
)

参数

requestId

string。要过滤的请求的 ID。您可以在传递到任何 webRequest 事件监听器中的 details 对象中获取此 ID。

返回值

一个 webRequest.StreamFilter 对象,您可以使用它来监控和修改响应。

示例

此示例展示了一个最小实现,它会通过流数据并将过滤器流在流完成接收数据后关闭。代码将从 webRequest 事件监听器中调用,事件监听器提供 details

js
let filter = browser.webRequest.filterResponseData(details.requestId);
filter.ondata = (event) => {
  console.log(`filter.ondata received ${event.data.byteLength} bytes`);
  filter.write(event.data);
};
filter.onstop = (event) => {
  // The extension should always call filter.close() or filter.disconnect()
  // after creating the StreamFilter, otherwise the response is kept alive forever.
  // If processing of the response data is finished, use close. If any remaining
  // response data should be processed by Firefox, use disconnect.
  filter.close();
};

此示例取自 http-response 示例扩展,它在 webRequest.onBeforeRequest 中创建了一个过滤器,并使用它修改了响应的第一部分

js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  let decoder = new TextDecoder("utf-8");
  let encoder = new TextEncoder();

  filter.ondata = (event) => {
    let str = decoder.decode(event.data, { stream: true });
    // Just change any instance of Example in the HTTP response
    // to WebExtension Example.
    str = str.replace(/Example/g, "WebExtension Example");
    filter.write(encoder.encode(str));
    filter.disconnect();
  };

  return {};
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/*"], types: ["main_frame"] },
  ["blocking"],
);

扩展示例

注意: 上面的示例仅适用于不是分块或流式传输的小型请求。更高级的示例在 webRequest.StreamFilter.ondata 中有记录。

浏览器兼容性

BCD 表格仅在浏览器中加载