# @adguard/tswebextension 中文文档 规范地址：https://npmcn.com/package/%40adguard/tswebextension/ 版本：6\.0\.1 npm 元数据更新时间：2026-10-15T16:41:05.436Z 中文译文更新时间：2026-11-08T11:29:25.796Z 软件包许可：GPL-3\.0-only 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40adguard/tswebextension 原文对照：https://npmcn.com/package/%40adguard/tswebextension/?lang=original 项目主页：https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tswebextension#readme 源码仓库：https://github.com/AdGuardSoftwareLimited/ext-tsurlfilter ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2 MB，293 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：21 个 - 首次发布：2022-06-17T13:59:41.560Z - 最新版本发布：2026-10-15T16:41:05.211Z - 近 30 天下载量：1786（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：186（近 12 个月 23 个） ## 中文简介 这是执行 AdGuard 扩展 API 的 TypeScript 库 ## 安装 ```sh npm install @adguard/tswebextension ``` 也可以使用：`pnpm add @adguard/tswebextension`、`yarn add @adguard/tswebextension`、`bun add @adguard/tswebextension` ## README # TSWeb 扩展 TypeScript 库,用于覆盖 tsurlfilter 库的网络扩展 api . 目录 : - [TSWeb 扩展](https://npmcn.com/package/%40adguard/tswebextension/#readme-tswebextension) - [浏览器兼容性](https://npmcn.com/package/%40adguard/tswebextension/#readme-browser-compatibility) - [安装](https://npmcn.com/package/%40adguard/tswebextension/#readme-install) - [使用量](https://npmcn.com/package/%40adguard/tswebextension/#readme-usage) - [国 际](https://npmcn.com/package/%40adguard/tswebextension/#readme-cli) - [副作用](https://npmcn.com/package/%40adguard/tswebextension/#readme-side-effects) - [API 密码](https://npmcn.com/package/%40adguard/tswebextension/#readme-api) - [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) - [我们的展出](https://npmcn.com/package/%40adguard/tswebextension/#readme-tswebextension_version) - [已删除的( C)](https://npmcn.com/package/%40adguard/tswebextension/#readme-extended_css_version) - [过滤器(仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-filters-mv2-only) - [过滤器](https://npmcn.com/package/%40adguard/tswebextension/#readme-filterid) - [内容](https://npmcn.com/package/%40adguard/tswebextension/#readme-content) - [信赖](https://npmcn.com/package/%40adguard/tswebextension/#readme-trusted) - [静态FiltersIds(仅限MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-staticfiltersids-mv3-only) - [自定义过滤器( 只有MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-customfilters-mv3-only) - [过滤器](https://npmcn.com/package/%40adguard/tswebextension/#readme-filterid-1) - [内容](https://npmcn.com/package/%40adguard/tswebextension/#readme-content-1) - [转换数据](https://npmcn.com/package/%40adguard/tswebextension/#readme-conversiondata) - [过滤 Path( 仅限MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-filterspath-mv3-only) - [规则Path(仅限MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-rulesetspath-mv3-only) - [申报日志(仅限MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-declarativelogenabled-mv3-only) - [允许列表](https://npmcn.com/package/%40adguard/tswebextension/#readme-allowlist) - [信任的领域](https://npmcn.com/package/%40adguard/tswebextension/#readme-trusteddomains) - [用户规则(MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-userrules-mv2) - [内容](https://npmcn.com/package/%40adguard/tswebextension/#readme-content-2) - [转换数据](https://npmcn.com/package/%40adguard/tswebextension/#readme-conversiondata-1) - [用户规则(MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-userrules-mv3) - [内容](https://npmcn.com/package/%40adguard/tswebextension/#readme-content-3) - [转换数据](https://npmcn.com/package/%40adguard/tswebextension/#readme-conversiondata-2) - [动词(已过期)](https://npmcn.com/package/%40adguard/tswebextension/#readme-verbose-deprecated) - [日志级别](https://npmcn.com/package/%40adguard/tswebextension/#readme-loglevel) - [设置](https://npmcn.com/package/%40adguard/tswebextension/#readme-settings) - [允许列表 倒转](https://npmcn.com/package/%40adguard/tswebextension/#readme-allowlistinverted) - [允许列表](https://npmcn.com/package/%40adguard/tswebextension/#readme-allowlistenabled) - [收集数据](https://npmcn.com/package/%40adguard/tswebextension/#readme-collectstats) - [调试脚本](https://npmcn.com/package/%40adguard/tswebextension/#readme-debugscriptlets) - [已启用](https://npmcn.com/package/%40adguard/tswebextension/#readme-stealthmodeenabled) - [过滤已启用](https://npmcn.com/package/%40adguard/tswebextension/#readme-filteringenabled) - [文档锁定PageUrl](https://npmcn.com/package/%40adguard/tswebextension/#readme-documentblockingpageurl) - [助理乌尔](https://npmcn.com/package/%40adguard/tswebextension/#readme-assistanturl) - [gpcScriptUrl(仅限MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-gpcscripturl-mv3-only) - [隐藏文档参考文件ScriptUrl(仅限MV3)](https://npmcn.com/package/%40adguard/tswebextension/#readme-hidedocumentreferrerscripturl-mv3-only) - [隐形图形](https://npmcn.com/package/%40adguard/tswebextension/#readme-stealthconfig) - [自毁第一党曲奇](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructfirstpartycookies) - [自毁第一党曲奇时间](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructfirstpartycookiestime) - [自行破坏第三方饼干](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructthirdpartycookies) - [自毁的第三方曲奇时间](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructthirdpartycookiestime) - [隐藏参考文件](https://npmcn.com/package/%40adguard/tswebextension/#readme-hidereferrer) - [隐藏搜索查询](https://npmcn.com/package/%40adguard/tswebextension/#readme-hidesearchqueries) - [块ChromeClientData](https://npmcn.com/package/%40adguard/tswebextension/#readme-blockchromeclientdata) - [发送不跟踪](https://npmcn.com/package/%40adguard/tswebextension/#readme-senddonottrack) - [块WebRTC](https://npmcn.com/package/%40adguard/tswebextension/#readme-blockwebrtc) - [子网络扩展](https://npmcn.com/package/%40adguard/tswebextension/#readme-tswebextension-1) - [属性](https://npmcn.com/package/%40adguard/tswebextension/#readme-properties) - [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration-1) - [关于过滤日志Event](https://npmcn.com/package/%40adguard/tswebextension/#readme-onfilteringlogevent) - [已启动](https://npmcn.com/package/%40adguard/tswebextension/#readme-isstarted) - [方法](https://npmcn.com/package/%40adguard/tswebextension/#readme-methods) - [点数](https://npmcn.com/package/%40adguard/tswebextension/#readme-initstorage) - [开始( c)](https://npmcn.com/package/%40adguard/tswebextension/#readme-start) - [配置 ()](https://npmcn.com/package/%40adguard/tswebextension/#readme-configure) - [停止( )](https://npmcn.com/package/%40adguard/tswebextension/#readme-stop) - [打开助理 ()](https://npmcn.com/package/%40adguard/tswebextension/#readme-openassistant) - [关闭助理( C)](https://npmcn.com/package/%40adguard/tswebextension/#readme-closeassistant) - [获取规则](https://npmcn.com/package/%40adguard/tswebextension/#readme-getrulescount) - [检索规则节点](https://npmcn.com/package/%40adguard/tswebextension/#readme-retrieverulenode) - [获取MessageHandler ()](https://npmcn.com/package/%40adguard/tswebextension/#readme-getmessagehandler) - [设置 Filtering Enabled () (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setfilteringenabled-mv2-only) - [set CollectHitStats () (仅MV2) (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setcollecthitstats-mv2-only) - [设置调试脚本( )](https://npmcn.com/package/%40adguard/tswebextension/#readme-setdebugscriptlets) - [set. Stealth ModeEnabled () (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setstealthmodeenabled-mv2-only) - [(仅MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setselfdestructfirstpartycookies-mv2-only) - [(仅MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setselfdestructthirdpartycookies-mv2-only) - [set selfDestruct FirstPartyCookies Time () (仅限MV2) (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setselfdestructfirstpartycookiestime-mv2-only) - [set self Destruct 三相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相](https://npmcn.com/package/%40adguard/tswebextension/#readme-setselfdestructthirdpartycookiestime-mv2-only) - [set Hide Referrer () (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-sethidereferrer-mv2-only) - [set 隐藏搜索查询 () (仅MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-sethidesearchqueries-mv2-only) - [设置 BlockChrome ClientData () (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setblockchromeclientdata-mv2-only) - [set SendDo NotTrack () (仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setsenddonottrack-mv2-only) - [设置 BlockWebRTC () (仅MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-setblockwebrtc-mv2-only) - [公用事业](https://npmcn.com/package/%40adguard/tswebextension/#readme-utilities) - [获取过滤器Name](https://npmcn.com/package/%40adguard/tswebextension/#readme-getfiltername) - [是用户脚本ApiEnabled](https://npmcn.com/package/%40adguard/tswebextension/#readme-isuserscriptsapienabled) - [过滤日志 API(仅限MV2)](https://npmcn.com/package/%40adguard/tswebextension/#readme-filtering-log-api-mv2-only) - [事件](https://npmcn.com/package/%40adguard/tswebextension/#readme-events) - [发送请求](https://npmcn.com/package/%40adguard/tswebextension/#readme-sendrequest) - [选项卡重新装入](https://npmcn.com/package/%40adguard/tswebextension/#readme-tabreload) - [基本规则](https://npmcn.com/package/%40adguard/tswebextension/#readme-applybasicrule) - [应用化妆规则](https://npmcn.com/package/%40adguard/tswebextension/#readme-applycosmeticrule) - [应用Csp规则](https://npmcn.com/package/%40adguard/tswebextension/#readme-applycsprule) - [收到回复](https://npmcn.com/package/%40adguard/tswebextension/#readme-receiveresponse) - [饼干](https://npmcn.com/package/%40adguard/tswebextension/#readme-cookie) - [删除页眉](https://npmcn.com/package/%40adguard/tswebextension/#readme-removeheader) - [删除帕拉姆](https://npmcn.com/package/%40adguard/tswebextension/#readme-removeparam) - [替换规则](https://npmcn.com/package/%40adguard/tswebextension/#readme-replaceruleapply) - [内容过滤启动](https://npmcn.com/package/%40adguard/tswebextension/#readme-contentfilteringstart) - [内容过滤 完成](https://npmcn.com/package/%40adguard/tswebextension/#readme-contentfilteringfinish) - [隐形动作](https://npmcn.com/package/%40adguard/tswebextension/#readme-stealthaction) - [隐形 Allowlist 动作](https://npmcn.com/package/%40adguard/tswebextension/#readme-stealthallowlistaction) - [Js 导入](https://npmcn.com/package/%40adguard/tswebextension/#readme-jsinject) - [属性](https://npmcn.com/package/%40adguard/tswebextension/#readme-properties-1) - [运行于LogEvent](https://npmcn.com/package/%40adguard/tswebextension/#readme-onlogevent) - [方法](https://npmcn.com/package/%40adguard/tswebextension/#readme-methods-1) - [添加事件倾听器( )](https://npmcn.com/package/%40adguard/tswebextension/#readme-addeventlistener) - [发布 Event ()](https://npmcn.com/package/%40adguard/tswebextension/#readme-publishevent) ## 浏览器兼容性 | 浏览器 | 版本 | | --- | --- | | 基于铬的浏览器 MV2 | 106 (韩语) | | 基于铬的浏览器 MV3 | 121国道 | | 火花 | 78国 | | 火狐移动 | 113号 | ## 安装 ```sh pnpm add @adguard/tswebextension ``` ## 使用量 您可以在 `packages/examples/tswebextension-*` **说明:** 在运行已编译的应用程序之前, 加载可访问的网络资源以重定向规则 通过内置 cli : ```sh tswebextension war [path] ``` 或将装载纳入您的管道: ```ts import { copyWar, DEFAULT_WAR_PATH } from '@adguard/tswebextension/cli'; const build = async () => { ... await copyWar(DEFAULT_WAR_PATH); ... }; ``` 如果未定义路径, 资源将被装入 `build/war` 默认相对于您当前工作目录 ## 国 际 控制台接口为建筑扩展提供了有用的工具. ```text Usage: tswebextension [options] [command] CLI to some development utils Options: -V, --version output the version number -h, --help display help for command Commands: war [path] Downloads web accessible resources for redirect rules help [command] display help for command ``` ## 副作用 在这个项目中 `sideEffects` 字段定义如下: `package.json` 文件 : ```json "sideEffects": [ "dist/assistant-inject.js", "dist/content-script.js", "dist/content-script.mv3.js", "dist/gpc.mv3.js", "dist/hide-document-referrer.mv3.js" ] ``` 此配置表示指定的文件有副作用 不应该被捆绑者震倒。 这些文件将修改 二、全球范围,这对联合国 应用. 通过明确列出这些档案,确保列入 即使它们没有任何直接进口或 用于编码库其他地方的出口. 在内容脚本中,我们需要访问 `@adguard/assistant` 仅限 当用户点击“ 手动” 块广告时。 因此,我们标记了文件 与 `@adguard/assistant` 作为副作用。 我们还增加了一个要求 字段到配置对象,以确保将助手捆绑 在最后扩展名内,允许 `tswebextension` 装入 点播. 与活性注射方法相同 我们使用隐形选项 GPC 并隐藏 文档查询器。 这些选项的处理器将动态注册内容 脚本通过 `scripting.registerContentScript`。 。 。 . ## API 密码 图书馆的主要理念是提供一个共同的界面 用于不同浏览器和显示版本 通过 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 对象. [子网络扩展](https://npmcn.com/package/%40adguard/tswebextension/#readme-tswebextension-1) 类提供了一套方法 用于从扩展的背景上下文过滤内容. MV2子模块还提供了一套方法用于 [过滤日志管理](https://npmcn.com/package/%40adguard/tswebextension/#readme-filtering-log-api-mv2-only)。 。 。 . ### 配置 类型 : `Configuration` 配置对象 . #### 我们的展出 类型 : `string` 图书馆版本. #### 已删除的( C) 类型 : `string` 扩展的 Css 模块版本,用于当前库版本. #### 过滤器(仅限MV2) 类型 : `FilterMV2[]` 过滤器列表. ##### 过滤器 类型 : `number` 过滤标识符 . ##### 内容 类型 : `Uint8Array[]` AGTree 字节缓冲块 . ##### 信赖 类型 : `boolean` 确定是否执行过滤列表js规则. #### 静态FiltersIds(仅限MV3) 类型 : `number[]` 静态过滤器标识列表. #### 自定义过滤器( 只有MV3) 类型 : `CustomFilterMV3[]` 用户可以添加/编辑/删除的自定义过滤器列表 . ##### 过滤器 类型 : `number` 过滤标识符 . ##### 内容 类型 : `string` 已转换过滤器列表内容(规则已转换为AdGuard格式). ##### 转换数据 类型 : `ConversionData` 数据转换自 `FilterList.getConversionData()`,包含: - `originals`: 已转换的规则正文组 - `conversions`: 将内容转换为原始数组索引的行首图抵消 #### 过滤 Path( 仅限MV3) 类型 : `string` 过滤列表文件的路径 . #### 规则Path(仅限MV3) 类型 : `string` 已转换规则集的目录路径 . #### 申报日志(仅限MV3) 类型 : `boolean` 允许匹配过滤日志的宣告规则. #### 允许列表 类型 : `string[]` 网站主机名或域列表,应当排除在外 禁止封锁或哪些应当包括在封锁中,取决于 数值 [允许列表 倒转](https://npmcn.com/package/%40adguard/tswebextension/#readme-allowlistinverted) 设置值. #### 信任的领域 类型 : `string[]` 网站域名列表,应当暂时排除在文档屏蔽之外. #### 用户规则(MV2) ##### 内容 类型 : `string` 已转换过滤器列表内容(规则已转换为AdGuard格式). ##### 转换数据 类型 : `ConversionData` 数据转换自 `FilterList.getConversionData()`,包含: - `originals`: 已转换的规则正文组 - `conversions`: 将内容转换为原始数组索引的行首图抵消 #### 用户规则(MV3) ##### 内容 类型 : `string` 已转换过滤器列表内容(规则已转换为AdGuard格式). ##### 转换数据 类型 : `ConversionData` 数据转换自 `FilterList.getConversionData()`,包含: - `originals`: 已转换的规则正文组 - `conversions`: 将内容转换为原始数组索引的行首图抵消 #### 动词(已过期) 类型 : `boolean | undefined` 负责伐木的可选旗. 默认为真. 将在下一个小版本中删除. #### 日志级别 类型 : `string | undefined` 设定日志级别、 默认为“ 错误 ” 的可选旗帜 . 可用的关卡 : 'error','warn','info','debug','trace' . #### 设置 类型 : `SettingsConfig` 设置配置对象 . ##### 允许列表 倒转 类型 : `boolean` 如果此旗帜属实, 应用程序将只对域工作 从 [允许列表](https://npmcn.com/package/%40adguard/tswebextension/#readme-allowlist),否则它会工作到任何地方 从列表中删除域 . ##### 允许列表 类型 : `boolean` 标记指定 [允许列表](https://npmcn.com/package/%40adguard/tswebextension/#readme-allowlist) 启用状态。 我们不用 计算启用状态的允许列表数组长度条件, 因为它不是用倒置模式的空列表覆盖大小写. ##### 收集数据 类型 : `boolean` 启用 Css 点击计数器, 如果为真 . ##### 调试脚本 可选类型 : `boolean` 默认为假. 如果为真,则启用控制台中的脚本记录 . ##### 已启用 类型 : `boolean` 如果为真, 启用隐形模式 . ##### 过滤已启用 类型 : `boolean` 如果为真, 启用过滤 . ##### 文档锁定PageUrl 类型 : `string` 重定向 URL 用于屏蔽规则 `$document` 修饰相. ##### 助理乌尔 类型 : `string` 组装的路径 `@adguard/assistant` 模块。 需要为助理的懒惰需求加载. ##### gpcScriptUrl(仅限MV3) 类型 : `string` 设置 GPC 信号的内容脚本路径 。 所需时间 `Do Not Track` 隐形选项 . ##### 隐藏文档参考文件ScriptUrl(仅限MV3) 类型 : `string` 隐藏文档引用者的内容脚本路径 . 所需时间 `Hide Search Queries` 隐形选项 . ##### 隐形图形 类型 : `StealthConfig` 隐形模式配置对象 . ###### 自毁第一党曲奇 类型 : `boolean` 如果应用程序设定固定寿命 从 [自毁第一党曲奇时间](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructfirstpartycookiestime) 给第一党饼干. ###### 自毁第一党曲奇时间 类型 : `number` 分钟内删除一党饼干. ###### 自行破坏第三方饼干 类型 : `boolean` 如果应用程序设定固定寿命 从 [自毁的第三方曲奇时间](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructthirdpartycookiestime) 第三方饼干. ###### 自毁的第三方曲奇时间 类型 : `number` 几分钟内删除第三方饼干. ###### 隐藏参考文件 类型 : `boolean` 申请是否将来源地裁判人隐藏在第三方 请求,用请求 url 替换裁判员 url . ###### 隐藏搜索查询 类型 : `boolean` 应用程序是否隐藏了搜索时的原裁判 在第三方查询中包含搜索查询的页面,替换 请求url的裁判员url. ###### 块ChromeClientData 类型 : `boolean` 对于 Google Chrome , 它删除“ X- Client- Data” 标题 包含浏览器版本信息的请求 和修改. ###### 发送不跟踪 类型 : `boolean` 在所有请求中包括 HTTP 标题“ DNT” 和“ Sec- GPC ” . 更多信息,请访问DNT: [https://en.wikipedia.org/wiki/Do not Track (英语)](https://en.wikipedia.org/wiki/Do_Not_Track)。 。 。 . 更多信息,请访问GPC: [https://globalprivaceycontrol.org (中文(简体) )](https://globalprivacycontrol.org/)。 。 。 . ###### 块WebRTC 类型 : `boolean` 屏蔽通过WebRTC泄露您IP地址的可能性,即使您使用代理服务器或VPN. ### 子网络扩展 #### 属性 ##### 配置 类型 : `ConfigurationMV2Context | ConfigurationMV3Context` 配置上下文,其中含有过滤引擎中装入的规则和域字符串被忽略的数组. 它用于在存储内存中的配置数据时降低内存消耗. ##### 关于过滤日志Event 类型 : `EventChannel` 事件频道 [过滤日志事件](https://npmcn.com/package/%40adguard/tswebextension/#readme-filtering-log-api-mv2-only)。 。 。 . ##### 已启动 类型 : `boolean` 应用开始. #### 方法 ##### 点数 类型 : `() => Promise` 初始化应用持久性数据 。 这个方法叫做尽快 并允许在 应用程序开始. ##### 开始( c) 类型 : `(configuration: TConfiguration) => Promise` 启动应用程序. 并按需要更新webRTC隐私.network设置并冲出浏览器内-memory请求缓存. ##### 配置 () 类型 : `(configuration: TConfiguration) => Promise` 更新配置. 并按需要更新webRTC隐私.network设置并冲出浏览器内-memory请求缓存. **MV3 处理出错 :** 当使用 Express V3 时, 页:1 `ConfigurationResult` 返回时间 `configure()` 财务报告和审定财务报表 `start()` 包含有错误和限制的多字段 那个 **必须检查**数字 : - **`staticFiltersStatus.errors`**: 阵列 `FailedEnableRulesetsError` 实例 `browser.declarativeNetRequest.updateEnabledRulesets` 失败. 浏览器不会更新或启用任何规则( 如果有) 未找到规则. - **`dynamicRules.errors`**: 发生转换错误的矩阵 在动态规则转换过程中(海关过滤器、用户规则、, 允许列表). - **`dynamicRules.limitations`**: 如果动态, 限制错误矩阵 由于浏览器限制,规则被切换. **这些错误没有抛出** 但结果却回来了. **您必须检查这些字段是否有重大错误并处理它们 适当** (如抛出,日志,通知用户). ```ts const result = await tsWebExtension.configure(configuration); // Check static filter errors if (result.staticFiltersStatus.errors.length > 0) { console.error('Failed to enable rulesets:', result.staticFiltersStatus.errors); } // Check dynamic rules errors and limitations if (result.dynamicRules) { if (result.dynamicRules.errors.length > 0) { console.error('Dynamic rules conversion errors:', result.dynamicRules.errors); } if (result.dynamicRules.limitations.length > 0) { console.warn('Dynamic rules were truncated:', result.dynamicRules.limitations); } } ``` ##### 停止( ) 类型 : `() => Promise` 停止应用. ##### 打开助理 () 类型 : `(tabId: number) => void` 在指定的标签中打开助手. ##### 关闭助理( C) 类型 : `(tabId: number) => void` ##### 获取规则 类型 : `() => number` 返回活动规则的数目. ##### 检索规则节点 类型 : `(filterId: number, ruleIndex: number): AnyRule | null` 通过过滤ID和规则索引从引擎中检索规则节点. ##### 获取MessageHandler () 类型 : `() => MessageHandlerMV2 | MessageHandlerMV3` 返回将收听内部信件的邮件处理器, 例如:用于计算内容标注的 css 消息. ##### 设置 Filtering Enabled () (仅限MV2) 类型 : `(isFilteringEnabled: boolean) => Promise` 更新 [过滤已启用](https://npmcn.com/package/%40adguard/tswebextension/#readme-filteringenabled) 不重新初始化引擎的配置值. 并按需要更新webRTC隐私.network设置并冲出浏览器内-memory请求缓存. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set CollectHitStats () (仅MV2) (仅限MV2) 类型 : `(isCollectStats: boolean) => void` 更新 [收集数据](https://npmcn.com/package/%40adguard/tswebextension/#readme-collectstats) 不重新初始化引擎的配置值. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### 设置调试脚本( ) 类型 : `(isDebugScriptlets: boolean) => void` 更新 [调试脚本](https://npmcn.com/package/%40adguard/tswebextension/#readme-debugscriptlets) 配置值 没有重新启动引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set. Stealth ModeEnabled () (仅限MV2) 类型 : `(value: isStealthModeEnabled) => Promise` 更新 [已启用](https://npmcn.com/package/%40adguard/tswebextension/#readme-stealthmodeenabled) 不重新初始化引擎的配置值. 同时按要求更新webRTC隐私.network设置. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### (仅MV2) 类型 : `(isSelfDestructFirstPartyCookies: boolean) => void` 更新 [自毁第一党曲奇](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructfirstpartycookies) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### (仅MV2) 类型 : `(isSelfDestructThirdPartyCookies: boolean) => void` 更新 [自行破坏第三方饼干](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructthirdpartycookies) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set selfDestruct FirstPartyCookies Time () (仅限MV2) (仅限MV2) 类型 : `(selfDestructFirstPartyCookiesTime: number) => void` 更新 [自毁第一党曲奇时间](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructfirstpartycookiestime) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set self Destruct 三相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 类型 : `(selfDestructThirdPartyCookiesTime: number) => void` 更新 [自毁的第三方曲奇时间](https://npmcn.com/package/%40adguard/tswebextension/#readme-selfdestructthirdpartycookiestime) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set Hide Referrer () (仅限MV2) 类型 : `(isHideReferrer: boolean) => void` 更新 [隐藏参考文件](https://npmcn.com/package/%40adguard/tswebextension/#readme-hidereferrer) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set 隐藏搜索查询 () (仅MV2) 类型 : `(isHideSearchQueries: boolean) => void` 更新 [隐藏搜索查询](https://npmcn.com/package/%40adguard/tswebextension/#readme-hidesearchqueries) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### 设置 BlockChrome ClientData () (仅限MV2) 类型 : `(isBlockChromeClientData: boolean) => void` 更新 [块ChromeClientData](https://npmcn.com/package/%40adguard/tswebextension/#readme-blockchromeclientdata) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### set SendDo NotTrack () (仅限MV2) 类型 : `(isSendDoNotTrack: boolean) => void` 更新 [发送不跟踪](https://npmcn.com/package/%40adguard/tswebextension/#readme-senddonottrack) 隐藏配置值而不重新初始化引擎. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ##### 设置 BlockWebRTC () (仅MV2) 类型 : `(isBlockWebRTC: boolean) => Promise` 更新 [块WebRTC](https://npmcn.com/package/%40adguard/tswebextension/#readme-blockwebrtc) 隐藏配置值而不重新初始化引擎. 同时按要求更新webRTC隐私.network设置. 如果 [配置](https://npmcn.com/package/%40adguard/tswebextension/#readme-configuration) 未设置. ## 公用事业 可在扩展中使用的公用事业的单独切入点. 可以这样进口: ```ts import { getFilterName, isUserScriptsApiEnabled } from '@adguard/tswebextension/mv3/utils'; ``` ### 获取过滤器Name 类型 : `(filterId: number) => string` 对于指定的过滤器标识符,将生成过滤器文件名 中,应当保存文本过滤规则. ### 是用户脚本ApiEnabled 类型 : `() => boolean` 回返 `true` 如果用户脚本 API 可用并启用, `false` 否则. ## 过滤日志 API(仅限MV2) 提供一套方法用于: [过滤日志事件](https://npmcn.com/package/%40adguard/tswebextension/#readme-filtering-log-api-mv2-only) 管理层. ### 事件 #### 发送请求 类型 : `SendRequestEvent` 奉命派遣. #### 选项卡重新装入 类型 : `TabReloadEvent` 重新装入标签. #### 基本规则 类型 : `ApplyBasicRuleEvent` 根据请求发送了块或允许列表规则匹配. #### 应用化妆规则 类型 : `ApplyCosmeticRuleEvent` 发布在elemhide, css或html规则应用上. #### 应用Csp规则 类型 : `ApplyCspRuleEvent` 执行Csp规则. #### 收到回复 类型 : `ReceiveResponseEvent` 接到答复就发出通知. #### 饼干 类型 : `CookieEvent` 发送到饼干移除或修改. #### 删除页眉 类型 : `RemoveHeaderEvent` 根据请求发送或删除回复信头. #### 删除帕拉姆 类型 : `RemoveParamEvent` 根据请求或答复发出撤换请求. #### 替换规则 类型 : `ReplaceRuleApplyEvent` 已通知适用替换规则. #### 内容过滤启动 类型 : `ContentFilteringStartEvent` 发送到内容过滤开始. #### 内容过滤 完成 类型 : `ContentFilteringFinishEvent` 发送到内容过滤端. #### 隐形动作 类型 : `StealthActionEvent` 秘密行动. #### 隐形 Allowlist 动作 类型 : `StealthAllowlistActionEvent` 负责防止秘密行动 `$stealth` 规则. #### Js 导入 类型 : `JsInjectEvent` 发送到 js 注入页面上下文 . ### 属性 #### 运行于LogEvent 类型 : `EventChannel` 事件频道 [过滤日志事件](https://npmcn.com/package/%40adguard/tswebextension/#readme-filtering-log-api-mv2-only)。 。 。 . ### 方法 #### 添加事件倾听器( ) 类型 : ```ts (type: T, listener: FilteringLogListener>) => void ``` 注册指定的过滤事件类型的听众. #### 发布 Event () 类型 : ```ts (event: T) => void ``` 发送指定的过滤事件 . ## 文档 - [更改日志](https://npmcn.com/package/%40adguard/tswebextension/CHANGELOG.md) - [发展指南](https://npmcn.com/package/DEVELOPMENT.md) - [LLM 代理规则](https://npmcn.com/package/%40adguard/tswebextension/AGENTS.md) ## 常见问题 ### @adguard/tswebextension 是什么？ 这是执行 AdGuard 扩展 API 的 TypeScript 库 ### 如何安装 @adguard/tswebextension？ 在项目目录运行 npm install @adguard/tswebextension，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 tswebextension，可以用 npx tswebextension 直接运行。 ### @adguard/tswebextension 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @adguard/tswebextension 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @adguard/tswebextension 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @adguard/tswebextension 可以商用吗？ @adguard/tswebextension 使用 GPL-3\.0-only 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。 ### @adguard/tswebextension 的下载量有多少？ 根据 npm 官方下载统计，@adguard/tswebextension 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,786 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @adguard/tswebextension 还在维护吗？ 最新版本 6\.0\.1 发布于 2026/10/16（23 天前）；至今共发布 186 个版本，其中过去 12 个月发布了 23 个；首次发布于 2022/06/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。