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 表格仅在浏览器中加载