@adguard/tswebextension

中文文档

6.0.1发布于 2026/10/16GPL-3.0-onlyTypeScriptES Module近 30 天下载 1786

这是执行 AdGuard 扩展 API 的 TypeScript 库

文档目录16 节

浏览器兼容性
安装
使用量
国际
副作用
API 密码
配置
子网络扩展
公用事业
获取过滤器Name
是用户脚本ApiEnabled
过滤日志 API(仅限MV2)
事件
属性
方法
文档

TSWeb 扩展

TypeScript 库,用于覆盖 tsurlfilter 库的网络扩展 api .

TSWeb 扩展

浏览器兼容性

浏览器	版本
基于铬的浏览器 MV2	106 (韩语)
基于铬的浏览器 MV3	121国道
火花	78国
火狐移动	113号

安装

pnpm add @adguard/tswebextension

使用量

您可以在 packages/examples/tswebextension-*

说明:

在运行已编译的应用程序之前, 加载可访问的网络资源以重定向规则

通过内置 cli :

tswebextension war [path]

或将装载纳入您的管道:

import { copyWar, DEFAULT_WAR_PATH } from '@adguard/tswebextension/cli';

const build = async () => {
    ...
    await copyWar(DEFAULT_WAR_PATH);
    ...
};

如果未定义路径, 资源将被装入 build/war 默认相对于您当前工作目录

国际

控制台接口为建筑扩展提供了有用的工具.

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 文件 :

"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 密码

图书馆的主要理念是提供一个共同的界面用于不同浏览器和显示版本通过配置对象.

子网络扩展类提供了一套方法用于从扩展的背景上下文过滤内容.

MV2子模块还提供了一套方法用于过滤日志管理。。。 .

配置

类型 : 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[]

网站主机名或域列表,应当排除在外禁止封锁或哪些应当包括在封锁中,取决于数值允许列表倒转设置值.

信任的领域

类型 : 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

如果此旗帜属实, 应用程序将只对域工作从允许列表,否则它会工作到任何地方从列表中删除域 .

允许列表

类型 : boolean

标记指定允许列表启用状态。我们不用计算启用状态的允许列表数组长度条件, 因为它不是用倒置模式的空列表覆盖大小写.

收集数据

类型 : 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

如果应用程序设定固定寿命从自毁第一党曲奇时间给第一党饼干.

自毁第一党曲奇时间

类型 : number

分钟内删除一党饼干.

自行破坏第三方饼干

类型 : boolean

如果应用程序设定固定寿命从自毁的第三方曲奇时间第三方饼干.

自毁的第三方曲奇时间

类型 : 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 (英语)。。。 .

更多信息,请访问GPC: https://globalprivaceycontrol.org (中文(简体) )。。。 .

块WebRTC

类型 : boolean

屏蔽通过WebRTC泄露您IP地址的可能性,即使您使用代理服务器或VPN.

子网络扩展

属性

配置

类型 : ConfigurationMV2Context | ConfigurationMV3Context

配置上下文,其中含有过滤引擎中装入的规则和域字符串被忽略的数组.

它用于在存储内存中的配置数据时降低内存消耗.

关于过滤日志Event

类型 : EventChannel<FilteringLogEvent>

事件频道过滤日志事件。。。 .

已启动

类型 : boolean

应用开始.

方法

点数

类型 : () => Promise<void>

初始化应用持久性数据。这个方法叫做尽快并允许在应用程序开始.

开始( c)

类型 : (configuration: TConfiguration) => Promise<TConfigurationResult>

启动应用程序.

并按需要更新webRTC隐私.network设置并冲出浏览器内-memory请求缓存.

配置 ()

类型 : (configuration: TConfiguration) => Promise<TConfigurationResult>

更新配置.

并按需要更新webRTC隐私.network设置并冲出浏览器内-memory请求缓存.

MV3 处理出错 : 当使用 Express V3 时, 页:1 ConfigurationResult 返回时间 configure() 财务报告和审定财务报表 start() 包含有错误和限制的多字段那个 必须检查数字 :

staticFiltersStatus.errors: 阵列 FailedEnableRulesetsError 实例 browser.declarativeNetRequest.updateEnabledRulesets 失败. 浏览器不会更新或启用任何规则( 如果有) 未找到规则.
dynamicRules.errors: 发生转换错误的矩阵在动态规则转换过程中(海关过滤器、用户规则、, 允许列表).
dynamicRules.limitations: 如果动态, 限制错误矩阵由于浏览器限制,规则被切换.

这些错误没有抛出 但结果却回来了. 您必须检查这些字段是否有重大错误并处理它们适当 (如抛出,日志,通知用户).

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<void>

停止应用.

打开助理 ()

类型 : (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<void>

更新过滤已启用不重新初始化引擎的配置值.

并按需要更新webRTC隐私.network设置并冲出浏览器内-memory请求缓存.

如果配置未设置.

set CollectHitStats () (仅MV2) (仅限MV2)

类型 : (isCollectStats: boolean) => void

更新收集数据不重新初始化引擎的配置值.

如果配置未设置.

设置调试脚本( )

类型 : (isDebugScriptlets: boolean) => void

更新调试脚本配置值没有重新启动引擎.

如果配置未设置.

set. Stealth ModeEnabled () (仅限MV2)

类型 : (value: isStealthModeEnabled) => Promise<void>

更新已启用不重新初始化引擎的配置值.

同时按要求更新webRTC隐私.network设置.

如果配置未设置.

(仅MV2)

类型 : (isSelfDestructFirstPartyCookies: boolean) => void

更新自毁第一党曲奇隐藏配置值而不重新初始化引擎.

如果配置未设置.

(仅MV2)

类型 : (isSelfDestructThirdPartyCookies: boolean) => void

更新自行破坏第三方饼干隐藏配置值而不重新初始化引擎.

如果配置未设置.

set selfDestruct FirstPartyCookies Time () (仅限MV2) (仅限MV2)

类型 : (selfDestructFirstPartyCookiesTime: number) => void

更新自毁第一党曲奇时间隐藏配置值而不重新初始化引擎.

如果配置未设置.

set self Destruct 三相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相

类型 : (selfDestructThirdPartyCookiesTime: number) => void

更新自毁的第三方曲奇时间隐藏配置值而不重新初始化引擎.

如果配置未设置.

set Hide Referrer () (仅限MV2)

类型 : (isHideReferrer: boolean) => void

更新隐藏参考文件隐藏配置值而不重新初始化引擎.

如果配置未设置.

set 隐藏搜索查询 () (仅MV2)

类型 : (isHideSearchQueries: boolean) => void

更新隐藏搜索查询隐藏配置值而不重新初始化引擎.

如果配置未设置.

设置 BlockChrome ClientData () (仅限MV2)

类型 : (isBlockChromeClientData: boolean) => void

更新块ChromeClientData 隐藏配置值而不重新初始化引擎.

如果配置未设置.

set SendDo NotTrack () (仅限MV2)

类型 : (isSendDoNotTrack: boolean) => void

更新发送不跟踪隐藏配置值而不重新初始化引擎.

如果配置未设置.

设置 BlockWebRTC () (仅MV2)

类型 : (isBlockWebRTC: boolean) => Promise<void>

更新块WebRTC 隐藏配置值而不重新初始化引擎.

同时按要求更新webRTC隐私.network设置.

如果配置未设置.

公用事业

可在扩展中使用的公用事业的单独切入点.

可以这样进口:

import { getFilterName, isUserScriptsApiEnabled } from '@adguard/tswebextension/mv3/utils';

获取过滤器Name

类型 : (filterId: number) => string

对于指定的过滤器标识符,将生成过滤器文件名中,应当保存文本过滤规则.

是用户脚本ApiEnabled

类型 : () => boolean

回返 true 如果用户脚本 API 可用并启用, false 否则.

过滤日志 API(仅限MV2)

提供一套方法用于: 过滤日志事件管理层.

事件

发送请求

类型 : 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<FilteringLogEvent>

事件频道过滤日志事件。。。 .

方法

添加事件倾听器( )

类型 :

<T extends FilteringEventType>(type: T, listener: FilteringLogListener<ExtractedFilteringLogEvent<T>>) => void

注册指定的过滤事件类型的听众.

发布 Event ()

类型 :

<T extends FilteringLogEvent>(event: T) => void

发送指定的过滤事件 .

文档

版本与发布记录

@adguard/tswebextension 共发布 186 个版本，首次发布于 2022/06/17；过去 12 个月发布了 23 个版本。

版本	发布日期	距今
`6.0.1`latest	2026/10/16	23 天前
`6.0.0`	2026/09/29	1 个月前
`6.0.0-beta.0`beta	2026/09/29	1 个月前
`5.0.3`	2026/08/25	2 个月前
`5.0.2`	2026/08/25	2 个月前
`5.0.1`	2026/08/21	2 个月前

其他发布通道：alpha → 3.1.0-alpha.4，beta → 6.0.0-beta.0。

关于 @adguard/tswebextension 的常见问题

@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 和提交记录判断。

npm install @adguard/tswebextension

pnpmpnpm add @adguard/tswebextension
yarnyarn add @adguard/tswebextension
bunbun add @adguard/tswebextension

命令行npx tswebextension

在你的项目目录中运行此命令。

近 30 天下载

1,786

约 1786 次日均 60 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，3 天前更新

最新版本6.0.1发布于 23 天前

开源许可GPL-3.0-only强 Copyleft

包体积2 MB293 个文件 · 解压后

运行依赖21 个

模块格式ES Module

TypeScript自带类型

Node.js>=22

发布版本186 个近 12 个月 23 个

首次发布2022/06/174 年前

元数据更新2026/10/16

每一个软件包背后，
都有分享与创造的人。

@adguard/tswebextension

TSWeb 扩展

浏览器兼容性

安装

使用量

国 际

副作用

API 密码

配置

我们的展出

已删除的( C)

过滤器(仅限MV2)

过滤器

内容

信赖

静态FiltersIds(仅限MV3)

自定义过滤器( 只有MV3)

过滤器

内容

转换数据

过滤 Path( 仅限MV3)

规则Path(仅限MV3)

申报日志(仅限MV3)

允许列表

信任的领域

用户规则(MV2)

内容

转换数据

用户规则(MV3)

内容

转换数据

动词(已过期)

日志级别

设置

允许列表 倒转

允许列表

收集数据

调试脚本

已启用

过滤已启用

文档锁定PageUrl

助理乌尔

gpcScriptUrl(仅限MV3)

隐藏文档参考文件ScriptUrl(仅限MV3)

隐形图形

自毁第一党曲奇

自毁第一党曲奇时间

自行破坏第三方饼干

自毁的第三方曲奇时间

隐藏参考文件

隐藏搜索查询

块ChromeClientData

发送不跟踪

块WebRTC

子网络扩展

属性

配置

关于过滤日志Event

已启动

方法

点数

开始( c)

配置 ()

停止( )

打开助理 ()

关闭助理( C)

获取规则

检索规则节点

获取MessageHandler ()

设置 Filtering Enabled () (仅限MV2)

set CollectHitStats () (仅MV2) (仅限MV2)

设置调试脚本( )

set. Stealth ModeEnabled () (仅限MV2)

(仅MV2)

(仅MV2)

set selfDestruct FirstPartyCookies Time () (仅限MV2) (仅限MV2)

set Hide Referrer () (仅限MV2)

set 隐藏搜索查询 () (仅MV2)

设置 BlockChrome ClientData () (仅限MV2)

set SendDo NotTrack () (仅限MV2)

国际

允许列表倒转

内容过滤完成