How to create your own ad filters
如何创建您自己的广告过滤器
In this article, we explain how to write custom filtering rules for use in AdGuard products. To test your rules, you can download the AdGuard app
在本文中,我们将解释如何编写在 AdGuard 产品中使用的自定义过滤规则。要测试您的规则,您可以下载 AdGuard 应用程序
A filter is a set of filtering rules applied to specific content, such as banners or pop-ups. AdGuard has a list of standard filters created by our team. We constantly improve and update them, striving to meet the needs of most of our users.
过滤器是一组应用于特定内容(例如横幅或弹出窗口)的过滤规则。 AdGuard 有我们团队创建的标准过滤器列表。我们不断改进和更新它们,努力满足大多数用户的需求。
At the same time, AdGuard allows you to create your own custom filters using the same types of rules that we have in our filters.
同时,AdGuard 允许您使用与我们过滤器中相同类型的规则来创建自己的自定义过滤器。
To describe the syntax of our filtering rules, we use Augmented BNF for Syntax Specifications, but we do not always strictly follow this specification.
为了描述过滤规则的语法,我们使用增强 BNF 语法规范,但我们并不总是严格遵循此规范。
Originally, the AdGuard's syntax was based on the syntax of Adblock Plus rules. Later, we extended it with new types of rules for better ad filtering. Some parts of this article about the rules common both to AdGuard and ABP were taken from the Adblock Plus guide on how to write filters.
最初,AdGuard 的语法是基于 Adblock Plus 规则的语法。后来,我们用新类型的规则对其进行了扩展,以实现更好的广告过滤。本文中有关 AdGuard 和 ABP 通用规则的某些部分摘自有关如何编写过滤器的 Adblock Plus 指南。
Comments 评论
Any line that starts with an exclamation mark is a comment. In the list of rules it is displayed in gray color. AdGuard will ignore this line, so you can write anything you want. Comments are usually placed above the rules and used to describe what a rule does.
任何以感叹号开头的行都是注释。在规则列表中,它以灰色显示。 AdGuard 将忽略这一行,因此您可以编写任何您想要的内容。注释通常放置在规则之上,用于描述规则的作用。
For example: 例如:
! This is the comment. Below this line, there is an actual filtering rule.
||example.org^
Examples 示例
Blocking by domain name 通过域名屏蔽
This rule blocks: 该规则阻止:
http://example.org/ad1.gif
http://subdomain.example.org/ad1.gif
https://ads.example.org:8000/
This rule does not block:
该规则不会阻止:
http://ads.example.org.us/ad1.gif
http://example.com/redirect/http://ads.example.org/
By default, such rules do not work for document requests. This means that the ||example.org^
rule will block a request made to example.org
when you try to navigate to this domain from another website, but if you type example.org
into the address bar and try to navigate to it, the website will open. To block the document request, you will need to use a rule with the $document
modifier: ||example.org^$document
.
默认情况下,此类规则不适用于文档请求。这意味着当您尝试从另一个网站导航到该域时, ||example.org^
规则将阻止向example.org
发出的请求,但如果您在地址栏中键入example.org
并尝试导航到它,网站将打开。要阻止文档请求,您需要使用带有$document
修饰符的规则: ||example.org^$document
。
Blocking exact address 阻止确切地址
This rule blocks: 该规则阻止:
http://example.org/
This rule does not block:
该规则不会阻止:
https://example.org/banner/img
Basic rule modifiers 基本规则修改器
Filtering rules support numerous modifiers that allow you to fine-tune the rule behavior. Here is an example of a rule with some simple modifiers.
过滤规则支持多种修饰符,允许您微调规则行为。下面是带有一些简单修饰符的规则示例。
This rule blocks: 该规则阻止:
http://example.org/script.js
if this script is loaded fromexample.com
.http://example.org/script.js
如果此脚本是从example.com
加载的。
This rule does not block:
该规则不会阻止:
https://example.org/script.js
if this script is loaded fromexample.org
.https://example.org/script.js
如果此脚本是从example.org
加载的。https://example.org/banner.png
because it is not a script.
https://example.org/banner.png
因为它不是脚本。
Unblocking an address 解锁地址
This rule unblocks: 此规则解锁:
http://example.org/banner.png
even if there is a blocking rule for this address.http://example.org/banner.png
即使该地址有阻止规则。
Blocking rules with $important
modifier can override exceptions.
使用$important
修饰符阻止规则可以覆盖异常。
Unblocking an entire website
解锁整个网站
This rule unblocks 这条规则解锁
- It disables all cosmetic rules on
example.com
.
它禁用example.com
上的所有修饰规则。 - It unblocks all requests sent from this website even if there is are blocking rules matching these requests.
即使存在与这些请求匹配的阻止规则,它也会取消阻止从此网站发送的所有请求。
Cosmetic rule 美容法则
Cosmetic rules are based on using a special language named CSS, which every browser understands. Basically, it adds a new CSS style to the website which purpose is to hide particular elements. You can learn more about CSS in general here.
外观规则基于使用一种名为 CSS 的特殊语言,每个浏览器都能理解这种语言。基本上,它向网站添加了新的 CSS 样式,其目的是隐藏特定元素。您可以在此处了解有关 CSS 的更多一般信息。
AdGuard extends CSS and lets filters developers handle much more complicated cases. However, to use these extended rules, you need to be fluent in regular CSS.
AdGuard扩展了 CSS ,让过滤器开发人员可以处理更复杂的情况。但是,要使用这些扩展规则,您需要精通常规 CSS。
Popular CSS selectors 流行的 CSS 选择器
Name 姓名 | CSS selector CSS 选择器 | Description 描述 |
---|---|---|
ID selector ID选择器 | #banners | Matches all elements with id attribute equal to banners .匹配 id 属性等于banners 的所有元素。![]() |
Class selector 类选择器 | .banners | Matches all elements with class attribute containing banners .匹配 class 属性包含banners 的所有元素。![]() |
Attribute selector 属性选择器 | div[class="banners"] | Matches all div elements with class attribute exactly equal to banners .匹配 class 属性完全等于banners 的所有div 元素。![]() |
Attribute substring selector 属性子串选择器 | div[class^="advert1"] | Matches all div elements which class attribute starts with the advert1 string.匹配 class 属性以advert1 字符串开头的所有div 元素。![]() |
Attribute substring selector 属性子串选择器 | div[class$="banners_ads"] | Matches all div elements which class attribute ends with the banners_ads string.匹配 class 属性以banners_ads 字符串结尾的所有div 元素。![]() |
Attribute substring selector 属性子串选择器 | a[href^="http://example.com/"] | Matches all links that are loaded from http://example.com/ domain.匹配从 http://example.com/ 域加载的所有链接。![]() |
Attribute selector 属性选择器 | a[href="http://example.com/"] | Matches all links to exactly the http://example.com/ address.将所有链接与 http://example.com/ 地址完全匹配。![]() |
Restrictions and limitations
限制和限制
Trusted filters 值得信赖的过滤器
Some rules can be used only in trusted filters. This category includes:
某些规则只能在受信任的过滤器中使用。该类别包括:
- filter lists created by the AdGuard team,
AdGuard 团队创建的过滤器列表, - custom filter lists installed as
trusted
,
自定义过滤器列表安装为trusted
, - user rules. 用户规则。
AdGuard Content Blocker AdGuard 内容拦截器
AdGuard Content Blocker is an extension for Samsung and Yandex browsers that can be installed from Google Play.
It is not to be confused with the fully functional AdGuard for Android that can only be downloaded from
our website. Unfortunately, AdGuard Content Blocker capabilities
are limited by what the browsers allow and they only support an old Adblock Plus filters syntax:
AdGuard Content Blocker 是 Samsung 和 Yandex 浏览器的扩展,可以从 Google Play 安装。
不要将其与功能齐全的 Android 版 AdGuard 相混淆,后者只能从
我们的网站。不幸的是,AdGuard 内容拦截器的功能受到浏览器允许的限制,并且它们仅支持旧的 Adblock Plus 过滤器语法:
- Basic blocking rules with the following modifiers:
$domain
,$third-party
, content-type modifiers.
具有以下修饰符的基本阻止规则:$domain
、$third-party
、 content-type modifiers 。 - Basic exception rules with the following modifiers:
$document
,$elemhide
.
具有以下修饰符的基本异常规则:$document
、$elemhide
。 - Basic element hiding rules with no extended CSS support.
没有扩展 CSS 支持的基本元素隐藏规则。
Because of the limitations above AdGuard Content Blocker will not be mentioned in the compatibility notes.
由于上述限制,AdGuard Content Blocker 将不会在兼容性说明中提及。
Basic rules 基本规则
The most simple rules are so-called Basic rules. They are used to block requests to specific URLs. Or to unblock it, if there is a special marker "@@" at the beginning of the rule.
最简单的规则就是所谓的基本规则。它们用于阻止对特定 URL 的请求。或者解除阻止,如果规则开头有特殊标记“@@”。
The basic principle for this type of rules is quite simple: you have to specify the address and additional parameters that limit or expand the rule scope.
此类规则的基本原理非常简单:您必须指定限制或扩展规则范围的地址和附加参数。
Basic rules for blocking requests are applied only to sub-requests. That means they will not block the loading of the page unless it is explicitly specified with a $document
modifier.
阻止请求的基本规则仅适用于子请求。这意味着它们不会阻止页面的加载,除非使用$document
修饰符显式指定。
Browser detects a blocked request as completed with an error.
浏览器检测到已阻止的请求已完成但有错误。
Rules shorter than 4 characters are considered incorrect and will be ignored.
少于 4 个字符的规则将被视为不正确并将被忽略。
Basic rule syntax 基本规则语法
rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]
pattern
— an address mask. Every request URL is collated to this mask. In the template, you can also use the special characters described below. Note that AdGuard truncates URLs to a length of 4096 characters in order to speed up matching and avoid issues with ridiculously long URLs.pattern
——地址掩码。每个请求 URL 都会与此掩码进行比较。在模板中,您还可以使用下面描述的特殊字符。请注意,AdGuard 将 URL 截断为 4096 个字符的长度,以加快匹配速度并避免出现 URL 过长的问题。@@
— a marker that is used in rules of exception. To turn off filtering for a request, start your rule with this marker.@@
— 在例外规则中使用的标记。要关闭对请求的过滤,请使用此标记开始您的规则。modifiers
— parameters that "clarify" the basic rule. Some of them limit the rule scope and some can completely change they way it works.modifiers
——“阐明”基本规则的参数。其中一些限制规则范围,一些可以完全改变规则的工作方式。
Special characters 特殊字符
*
— a wildcard character. It is used to represent any set of characters. This can also be an empty string or a string of any length.*
— 通配符。它用于表示任何字符集。这也可以是空字符串或任意长度的字符串。||
— an indication to apply the rule to the specified domain and its subdomains. With this character, you do not have to specify a particular protocol and subdomain in address mask. It means that||
stands forhttp://*.
,https://*.
,ws://*.
,wss://*.
at once.||
— 将规则应用于指定域及其子域的指示。使用此字符,您不必在地址掩码中指定特定协议和子域。这意味着||
代表http://*.
,https://*.
,ws://*.
,wss://*.
立刻。^
— a separator character mark. Separator character is any character, but a letter, a digit, or one of the following:_
-
.
%
. In this example separator characters are shown in bold:http:
//
example.com
/?
t=1
&
t2=t3
. The end of the address is also accepted as separator.^
— 分隔符标记。分隔符可以是任何字符,但字母、数字或以下字符之一:_
-
.
%
。在此示例中example.com
分隔符以粗体显示:http:
//
/?
t=1
&
t2=t3
。地址末尾也可以作为分隔符。|
— a pointer to the beginning or the end of address. The value depends on the character placement in the mask. For example, a ruleswf|
corresponds tohttp://example.com/annoyingflash.swf
, but not tohttp://example.com/swf/index.html
.|http://example.org
corresponds tohttp://example.org
, but not tohttp://domain.com?url=http://example.org
.|
— 指向地址开头或结尾的指针。该值取决于蒙版中的字符位置。例如,规则swf|
对应于http://example.com/annoyingflash.swf
,但不至于http://example.com/swf/index.html
。|http://example.org
对应于http://example.org
,但不对应于http://domain.com?url=http://example.org
。
|
, ||
, ^
can only be used with rules that have a URL pattern. For example, ||example.com##.advert
is incorrect and will be ignored by the blocker.|
, ||
, ^
只能与具有 URL 模式的规则一起使用。例如, ||example.com##.advert
不正确,将被拦截器忽略。
We also recommend to get acquainted with the Adblock Plus filter cheatsheet, for better understanding of how such rules should be made.
我们还建议您熟悉Adblock Plus 过滤器备忘单,以便更好地了解如何制定此类规则。
Regular expressions support
正则表达式支持
If you want even more flexibility in making rules, you can use Regular expressions instead of a default simplified mask with special characters.
如果您希望在制定规则时更加灵活,可以使用正则表达式而不是带有特殊字符的默认简化掩码。
Rules with regular expressions work more slowly, therefore it is recommended to avoid them or to limit their scope to specific domains.
使用正则表达式的规则运行速度较慢,因此建议避免使用它们或将其范围限制在特定域。
If you want a blocker to determine a regular expression, the pattern
has to look like this:
如果您希望阻止程序确定正则表达式, pattern
必须如下所示:
pattern = "/" regexp "/"
For example, /banner\d+/$third-party
this rule will apply the regular expression banner\d+
to all third-party requests. Exclusion rule with regular expression looks like this: @@/banner\d+/
.
例如, /banner\d+/$third-party
该规则将把正则表达式banner\d+
应用于所有第三方请求。正则表达式的排除规则如下所示: @@/banner\d+/
。
AdGuard Safari and AdGuard for iOS do not fully support regular expressions because of Content Blocking API restrictions (look for "The Regular expression format" section).
由于内容阻止 API 限制, AdGuard Safari 和 AdGuard for iOS 不完全支持正则表达式(请查找“正则表达式格式”部分)。
Wildcard support for TLD (top-level domains)
TLD(顶级域)的通配符支持
Wildcard characters are supported for TLDs of the domains in patterns of cosmetic, HTML filtering and JavaScript rules.
域的 TLD 支持通配符,格式为修饰、 HTML 过滤和JavaScript规则。
For cosmetic rules, e.g. example.*##.banner
, multiple domains are matched due to the part .*
, i.e. example.com
, sub.example.net
, example.co.uk
, etc.
对于修饰规则,例如example.*##.banner
,由于.*
部分而匹配多个域,即example.com
、 sub.example.net
、 example.co.uk
等。
For basic rules the described logic is applicable only for the domains specified in $domain
modifier, e.g. ||*/banners/*$image,domain=example.*
.
对于基本规则,所描述的逻辑仅适用于$domain
修饰符中指定的域,例如 ||*/banners/*$image,domain=example.*
。
In AdGuard for Windows, Mac, Android, and AdGuard Browser Extension rules with wildcard .*
match any public suffix (or eTLD). But for AdGuard for Safari and iOS the supported list of top-level domains is limited due to Safari limitations.
在 AdGuard for Windows、Mac、Android 和 AdGuard 浏览器扩展规则中,带有通配符.*
规则与任何公共后缀(或 eTLD)匹配。但对于适用于 Safari 和 iOS 的 AdGuard,由于 Safari 的限制,支持的顶级域列表有限。
Rules with wildcard for TLD are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持 TLD 通配符规则。
Basic rule examples 基本规则示例
||example.com/ads/*
— a simple rule, which corresponds to addresses likehttp://example.com/ads/banner.jpg
and evenhttp://subdomain.example.com/ads/otherbanner.jpg
.||example.com/ads/*
— 一个简单的规则,对应于如下地址http://example.com/ads/banner.jpg
甚至http://subdomain.example.com/ads/otherbanner.jpg
。||example.org^$third-party
— this rule blocks third-party requests toexample.org
and its subdomains.||example.org^$third-party
— 此规则阻止第三方对example.org
及其子域的请求。@@||example.com$document
— general exception rule. It completely disables filtering forexample.com
and all subdomains. There is a number of modifiers which can be used in exception rules. For more details, please follow the link below.@@||example.com$document
— 一般例外规则。它完全禁用对example.com
和所有子域的过滤。有许多修饰符可以在异常规则中使用。欲了解更多详情,请点击以下链接。
Basic rule modifiers 基本规则修改器
The features described in this section are intended for experienced users. They extend capabilities of "Basic rules", but in order to use them you need to have a basic understanding of the way your browser works.
本节中描述的功能适用于有经验的用户。它们扩展了“基本规则”的功能,但为了使用它们,您需要对浏览器的工作方式有基本的了解。
You can change the behavior of a "basic rule" by using additional modifiers. Modifiers should be located in the end of the rule after a $
sign and be separated by commas.
您可以使用其他修饰符来更改“基本规则”的行为。修饰符应位于规则末尾的$
符号之后,并用逗号分隔。
Example: 例子:
||domain.com^$popup,third-party
Basic modifiers 基本修饰符
The following modifiers are the most simple and frequently used.
Basically, they just limit the scope of rule application.
以下修饰符是最简单且最常用的。基本上,它们只是限制了规则的应用范围。
Modifier \ Products 改性剂\产品 | CoreLibs apps CoreLibs 应用程序 | AdGuard for Chromium 适用于 Chromium 的 AdGuard | AdGuard for Chrome MV3 适用于 Chrome 的 AdGuard MV3 | AdGuard for Firefox 适用于 Firefox 的 AdGuard | AdGuard for iOS iOS 版 AdGuard | AdGuard for Safari 适用于 Safari 的 AdGuard | AdGuard Content Blocker AdGuard 内容拦截器 |
---|---|---|---|---|---|---|---|
$app $应用程序 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$denyallow | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$domain $域名 | ✅ | ✅ | ✅ *[1] | ✅ | ✅ *[1] | ✅ *[1] | ✅ |
$header $标头 | ✅ | ✅ *[2] | ❌ | ✅ *[2] | ❌ | ❌ | ❌ |
$important $重要 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$match-case $匹配大小写 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$method $方法 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$popup $弹出窗口 | ✅ *[3] | ✅ | ✅ *[3] | ✅ | ✅ *[3] | ✅ *[3] | ❌ |
$strict-first-party $严格第一方 | ⏳ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$strict-third-party $严格第三方 | ⏳ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$third-party $第三方 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$to $至 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — fully supported ✅ — 完全支持
- ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
✅ * — 支持,但可靠性可能会有所不同或可能会出现限制;检查修改器描述以获取更多详细信息 - ⏳ — feature that is planned to be implemented but is not yet available in any product
⏳ — 计划实现但尚未在任何产品中提供的功能 - ❌ — not supported ❌ — 不支持
$app
This modifier lets you narrow the rule coverage down to a specific application (or a list of applications). This might be not too important on Windows and Mac, but this is very important on mobile devices where some of the filtering rules must be app-specific.
此修饰符可让您将规则覆盖范围缩小到特定应用程序(或应用程序列表)。这在 Windows 和 Mac 上可能不太重要,但在移动设备上非常重要,其中某些过滤规则必须特定于应用程序。
- Android — use the app package name, e.g.
org.example.app
.
Android — 使用应用程序包名称,例如org.example.app
。 - Windows — use the process name, e.g.
chrome.exe
.
Windows — 使用进程名称,例如chrome.exe
。 - Mac — use the bundle ID or the process name, e.g.
com.google.Chrome
.
Mac — 使用捆绑 ID 或进程名称,例如com.google.Chrome
。
For Mac, you can find out the bundle ID or the process name of the app by viewing the respective request details in the Filtering log.
对于 Mac,您可以通过查看过滤日志中的相应请求详细信息来查找应用程序的捆绑包 ID 或进程名称。
Examples 示例
||baddomain.com^$app=org.example.app
— a rule to block requests that match the specified mask and are sent from theorg.example.app
Android app.
||baddomain.com^$app=org.example.app
— 阻止与指定掩码匹配并从org.example.app
Android 应用发送的请求的规则。||baddomain.com^$app=org.example.app1|org.example.app2
— the same rule but it works for bothorg.example.app1
andorg.example.app2
apps.
||baddomain.com^$app=org.example.app1|org.example.app2
— 相同的规则,但它适用于org.example.app1
和org.example.app2
应用程序。
If you want the rule not to be applied to certain apps, start the app name with the ~
sign.
如果您希望规则不应用于某些应用程序,请以~
符号开头应用程序名称。
||baddomain.com^$app=~org.example.app
— a rule to block requests that match the specified mask and are sent from any app except for theorg.example.app
.
||baddomain.com^$app=~org.example.app
— 阻止与指定掩码匹配且从除org.example.app
之外的任何应用程序发送的请求的规则。||baddomain.com^$app=~org.example.app1|~org.example.app2
— same as above, but now two apps are excluded:org.example.app1
andorg.example.app2
.
||baddomain.com^$app=~org.example.app1|~org.example.app2
— 与上面相同,但现在排除了两个应用程序:org.example.app1
和org.example.app2
。
Apps in the modifier value cannot have a wildcard, e.g. $app=com.*.music
.
Rules with such modifier are considered invalid.
修饰符值中的应用程序不能有通配符,例如$app=com.*.music
。具有此类修饰符的规则被视为无效。
- Only AdGuard for Windows, Mac, Android are technically capable of using rules with
$app
modifier.
从技术上讲,只有适用于 Windows、Mac、Android 的 AdGuard 能够使用带有$app
修饰符的规则。 - On Windows the process name is case-insensitive starting with AdGuard for Windows with CoreLibs v1.12 or later.
在 Windows 上,从带有CoreLibs v1.12 或更高版本的 AdGuard for Windows 开始,进程名称不区分大小写。
$denyallow
$denyallow
modifier allows to avoid creating additional rules when it is needed to disable a certain rule for specific domains. $denyallow
matches only target domains and not referrer domains.$denyallow
修饰符允许在需要禁用特定域的特定规则时避免创建额外的规则。 $denyallow
仅匹配目标域而不匹配引荐来源域。
Adding this modifier to a rule is equivalent to excluding the domains by the rule's matching pattern or to adding the corresponding exclusion rules. To add multiple domains to one rule, use the |
character as a separator.
向规则添加此修饰符相当于通过规则的匹配模式排除域或添加相应的排除规则。要将多个域添加到一条规则,请使用|
字符作为分隔符。
Examples 示例
This rule: 这条规则:
*$script,domain=a.com|b.com,denyallow=x.com|y.com
is equivalent to this one:
相当于这个:
/^(?!.*(x.com|y.com)).*$/$script,domain=a.com|b.com
or to the combination of these three:
或这三者的组合:
*$script,domain=a.com|b.com
@@||x.com$script,domain=a.com|b.com
@@||y.com$script,domain=a.com|b.com
- The rule's matching pattern cannot target any specific domains, e.g. it cannot start with
||
.
规则的匹配模式不能针对任何特定域,例如它不能以||
开头。 。 - Domains in the modifier value cannot be negated, e.g.
$denyallow=~x.com
, or have a wildcard TLD, e.g.$denyallow=x.*
, or be a regular expression, e.g.$denyallow=/\.(com\|org)/
.
修饰符值中的域不能被否定,例如$denyallow=~x.com
,或者具有通配符 TLD,例如$denyallow=x.*
,或者是正则表达式,例如$denyallow=/\.(com\|org)/
. $denyallow
cannot be used together with$to
. It can be expressed with inverted$to
:$denyallow=a.com|b.com
is equivalent to$to=~a.com|~b.com
.$denyallow
不能与$to
一起使用。它可以用倒置的$to
表示:$denyallow=a.com|b.com
相当于$to=~a.com|~b.com
。
The rules which violate these restrictions are considered invalid.
违反这些限制的规则被视为无效。
Rules with $denyallow
modifier are not supported by AdGuard for iOS, Safari, and AdGuard Content Blocker.
适用于 iOS、Safari 的 AdGuard 和 AdGuard 内容拦截器不支持带有$denyallow
修饰符的规则。
$domain
$domain
limits the rule scope to requests made from the specified domains and their subdomains (as indicated by the Referer HTTP header).$domain
将规则范围限制为从指定域及其子域发出的请求(如Referer HTTP 标头所示)。
Syntax 句法
The modifier is a list of one or more expressions separated by the |
symbol, each of which is matched against a domain in a particular way depending on its type (see below).
修饰符是由|
分隔的一个或多个表达式的列表。符号,每个符号根据其类型以特定方式与域匹配(见下文)。
domains = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_domain / any_tld_domain / regexp )
regular_domain
— a regular domain name (domain.com
). Corresponds the specified domain and its subdomains. It is matched lexicographically.regular_domain
— 常规域名 (domain.com
)。对应指定的域及其子域。它是按字典顺序匹配的。any_tld_domain
— a domain name ending with a wildcard character as a public suffix, e.g. forexample.*
it isco.uk
inexample.co.uk
. Corresponds to the specified domain and its subdomains with any public suffix. It is matched lexicographically.any_tld_domain
— 以通配符结尾的域名作为公共后缀,例如example.*
它是example.co.uk
中的co.uk
。对应于指定的域及其带有任何公共后缀的子域。它是按字典顺序匹配的。regexp
— a regular expression, starts and ends with/
. The pattern works the same way as in the basic URL rules, but the characters/
,$
,,
, and|
must be escaped with\
.regexp
— 正则表达式,以/
开头和结尾。该模式的工作方式与基本 URL 规则相同,但字符/
、$
、,
和|
必须用\
转义。
Rules with $domain
modifier as regular_domain
are supported by all AdGuard products.
所有 AdGuard 产品都支持以$domain
修饰符作为regular_domain
的规则。
Examples 示例
Just $domain
:
只是$domain
:
||baddomain.com^$domain=example.org
blocks requests that match the specified mask, and are sent from domainexample.org
or its subdomains.
||baddomain.com^$domain=example.org
阻止与指定掩码匹配并从域example.org
或其子域发送的请求。||baddomain.com^$domain=example.org|example.com
— the same rule, but it works for bothexample.org
andexample.com
.
||baddomain.com^$domain=example.org|example.com
— 相同的规则,但它适用于example.org
和example.com
。
If you want the rule not to be applied to certain domains, start a domain name with ~
sign.
如果您希望规则不应用于某些域,请以~
符号开头的域名。
$domain
and negation ~
:$domain
和否定~
:
||baddomain.com^$domain=example.org
blocks requests that match the specified mask and are sent from theexample.org
domain or its subdomains.
||baddomain.com^$domain=example.org
阻止与指定掩码匹配并从example.org
域或其子域发送的请求。||baddomain.com^$domain=example.org|example.com
— the same rule, but it works for bothexample.org
andexample.com
.
||baddomain.com^$domain=example.org|example.com
— 相同的规则,但它适用于example.org
和example.com
。||baddomain.com^$domain=~example.org
blocks requests matching the pattern sent from any domain exceptexample.org
and its subdomains.
||baddomain.com^$domain=~example.org
阻止与除example.org
及其子域之外的任何域发送的模式匹配的请求。||baddomain.com^$domain=example.org|~foo.example.org
blocks requests sent fromexample.org
and its subdomains, except the subdomainfoo.example.org
.
||baddomain.com^$domain=example.org|~foo.example.org
阻止从example.org
及其子域(子域foo.example.org
除外)发送的请求。||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/
blocks requests sent fromexample.org
andexample.com
domains and all their subdomains.
||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/
阻止从example.org
和example.com
域及其所有子域发送的请求。||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/
blocks requests sent from any domains, excepta.com
,b
with any public suffix (b.com
,b.co.uk
, etc.),c.com
,c.org
, and their subdomains.
||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/
阻止从任何域发送的请求,除了a.com
、带有任何公共后缀(b.com
、b.co.uk
等)的b
、c.com
、c.org
及其子域。
$domain
modifier matching target domain:$domain
修饰符匹配目标域:
In some cases the $domain
modifier can match not only the referrer domain, but also the target domain. This happens when all the following conditions are met:
在某些情况下, $domain
修饰符不仅可以匹配引用域,还可以匹配目标域。当满足以下所有条件时会发生这种情况:
- The request has the
document
content type
请求具有document
内容类型 - The rule pattern does not match any particular domains
规则模式不匹配任何特定域 - The rule pattern does not contain regular expressions
规则模式不包含正则表达式 - The
$domain
modifier contains only excluded domains, e.g.$domain=~example.org|~example.com
$domain
修饰符仅包含排除的域,例如$domain=~example.org|~example.com
The following predicate should be satisfied to perform a target domain matching:
应满足以下谓词才能执行目标域匹配:
1 AND ((2 AND 3) OR 4)
That is, if the modifier $domain
contains only excluded domains, then the rule does not need to meet the second and third conditions to match the target domain against the modifier $domain
.
也就是说,如果修饰符$domain
仅包含排除的域,则规则不需要满足第二个和第三个条件即可将目标域与修饰符$domain
进行匹配。
If some of the conditions above are not met but the rule contains $cookie
or $csp
modifier, the target domain will still be matched.
如果不满足上述某些条件,但规则包含$cookie
或$csp
修饰符,则仍会匹配目标域。
If the referrer matches a rule with $domain
that explicitly excludes the referrer domain, then the rule will not be applied even if the target domain also matches the rule. This affects rules with $cookie
and $csp
modifiers, too.
如果引荐来源网址与$domain
显式排除引荐来源网址域的规则相匹配,则即使目标域也匹配该规则,也不会应用该规则。这也会影响带有$cookie
和$csp
修饰符的规则。
Examples 示例
*$cookie,domain=example.org|example.com
will block cookies for all requests to and fromexample.org
andexample.com
.
*$cookie,domain=example.org|example.com
将阻止来自example.org
和example.com
的所有请求的 cookie。*$document,domain=example.org|example.com
will block all requests to and fromexample.org
andexample.com
.
*$document,domain=example.org|example.com
将阻止所有发往和来自example.org
和example.com
请求。
In the following examples it is implied that requests are sent from http://example.org/page
(the referrer) and the target URL is http://targetdomain.com/page
.
在以下示例中,暗示请求是从http://example.org/page
(引荐来源网址)发送的,目标 URL 是http://targetdomain.com/page
。
page$domain=example.org
will be matched, as it matches the referrer domain.page$domain=example.org
将被匹配,因为它与引荐来源网址匹配。page$domain=targetdomain.com
will be matched, as it matches the target domain and satisfies all requirements mentioned above.page$domain=targetdomain.com
将被匹配,因为它匹配目标域并满足上述所有要求。||*page$domain=targetdomain.com
will not be matched, as the pattern||*page
may match specific domains, e.g.example.page
.
||*page$domain=targetdomain.com
将不匹配,因为模式||*page
可能匹配特定域,例如example.page
。||*page$domain=targetdomain.com,cookie
will be matched because the rule contains$cookie
modifier despite the pattern||*page
may match specific domains.
||*page$domain=targetdomain.com,cookie
将被匹配,因为规则包含$cookie
修饰符,尽管模式||*page
可能匹配特定域。/banner\d+/$domain=targetdomain.com
will not be matched as it contains a regular expression.
/banner\d+/$domain=targetdomain.com
将不会被匹配,因为它包含正则表达式。page$domain=targetdomain.com|~example.org
will not be matched because the referrer domain is explicitly excluded.
page$domain=targetdomain.com|~example.org
不会匹配,因为引用域已被明确排除。
$domain
modifier limitations
$domain
修饰符限制
In AdGuard for Chrome MV3, regexp
and any_tld_domain
entries are not supported.
在AdGuard for Chrome MV3中,不支持regexp
和any_tld_domain
条目。
Safari does not support the simultaneous use of allowed and disallowed domains, so rules like ||baddomain.com^$domain=example.org|~foo.example.org
will not work in AdGuard for iOS and AdGuard for Safari.
Safari 不支持同时使用允许和不允许的域,因此如下规则 ||baddomain.com^$domain=example.org|~foo.example.org
不适用于 iOS 版 AdGuard 和 Safari 版 AdGuard。
Rules with regular expressions in the $domain
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
使用CoreLibs v1.11 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及带有TSUrlFilter v3.0.0 或更高版本的 AdGuard 浏览器扩展支持$domain
修饰符中包含正则表达式的规则。
In AdGuard for Windows, Mac and Android with CoreLibs v1.12 or later the $domain
modifier can be alternatively spelled as $from
.
在带有CoreLibs v1.12 或更高版本的 Windows、Mac 和 Android 版 AdGuard 中, $domain
修饰符也可以拼写为$from
。
$header
The $header
modifier allows matching the HTTP response having a specific header with (optionally) a specific value.$header
修饰符允许将具有特定标头的 HTTP 响应与(可选)特定值进行匹配。
Syntax 句法
$header "=" h_name [":" h_value]
h_value = string / regexp
where: 在哪里:
h_name
— required, an HTTP header name. It is matched case-insensitively.h_name
— 必需,HTTP 标头名称。它的匹配不区分大小写。h_value
— optional, an HTTP header value matching expression, it may be one of the following:h_value
— 可选,HTTP 标头值匹配表达式,它可能是以下之一:string
— a sequence of characters. It is matched against the header value lexicographically;string
— 字符序列。它按字典顺序与标头值进行匹配;regexp
— a regular expression, starts and ends with/
. The pattern works the same way as in the basic URL rules, but the characters/
,$
and,
must be escaped with\
.regexp
— 正则表达式,以/
开头和结尾。该模式的工作方式与基本 URL 规则相同,但字符/
、$
和,
必须用\
转义。
The modifier part, ":" h_value
, may be omitted. In that case, the modifier matches the header name only.
修饰符部分":" h_value
可以省略。在这种情况下,修饰符仅匹配标头名称。
Examples 示例
||example.com^$header=set-cookie:foo
blocks requests whose responses have theSet-Cookie
header with the value matchingfoo
literally.
||example.com^$header=set-cookie:foo
阻止其响应具有Set-Cookie
标头且其值与字面匹配foo
的请求。||example.com^$header=set-cookie
blocks requests whose responses have theSet-Cookie
header with any value.
||example.com^$header=set-cookie
阻止其响应具有任意值的Set-Cookie
标头的请求。@@||example.com^$header=set-cookie:/foo\, bar\$/
unblocks requests whose responses have theSet-Cookie
header with value matching thefoo, bar$
regular expression.
@@||example.com^$header=set-cookie:/foo\, bar\$/
取消阻止其响应具有Set-Cookie
标头且其值与foo, bar$
正则表达式匹配的请求。@@||example.com^$header=set-cookie
unblocks requests whose responses have aSet-Cookie
header with any value.
@@||example.com^$header=set-cookie
取消阻止其响应具有任意值的Set-Cookie
标头的请求。
$header
modifier limitations
$header
修饰符限制
- The
$header
modifier can be matched only when headers are received. So if the request is blocked or redirected at an earlier stage, the modifier cannot be applied.
仅当收到标头时,$header
修饰符才能匹配。因此,如果请求在较早阶段被阻止或重定向,则无法应用修饰符。 - In Adguard Browser Extension, the
$header
modifier is only compatible with$csp
,$removeheader
,$important
, and$badfilter
.
在 Adguard 浏览器扩展中,$header
修饰符仅兼容$csp
、$removeheader
、$important
和$badfilter
。
Rules with the $header
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android
with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
使用CoreLibs v1.11 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及带有TSUrlFilter v3.0.0 或更高版本的 AdGuard 浏览器扩展支持使用$header
修饰符的规则。
$important
The $important
modifier applied to a rule increases its priority over rules without the identical modifier. Even over basic exception rules.
应用于规则的$important
修饰符会提高其相对于没有相同修饰符的规则的优先级。甚至超越基本的例外规则。
Go to rules priorities for more details.
请参阅规则优先级了解更多详细信息。
Examples 示例
! blocking rule will block all requests despite of the exception rule
||example.org^$important
@@||example.org^
! if the exception rule also has `$important` modifier, it will prevail and requests won't be blocked
||example.org^$important
@@||example.org^$important
$match-case
This modifier defines a rule which applies only to addresses that match the case. Default rules are case-insensitive.
此修饰符定义仅适用于与大小写匹配的地址的规则。默认规则不区分大小写。
Examples 示例
*/BannerAd.gif$match-case
— this rule will blockhttp://example.com/BannerAd.gif
, but nothttp://example.com/bannerad.gif
.*/BannerAd.gif$match-case
— 此规则将被阻止http://example.com/BannerAd.gif
,但不是http://example.com/bannerad.gif
。
Rules with the $match-case
are supported by AdGuard for iOS and AdGuard for Safari with SafariConverterLib v2.0.43 or later.
AdGuard for iOS 和 AdGuard for Safari 以及 SafariConverterLib v2.0.43 或更高版本支持使用$match-case
规则。
All other products already support this modifier.
所有其他产品都已支持此修饰符。
$method
This modifier limits the rule scope to requests that use the specified set of HTTP methods. Negated methods are allowed. The methods must be specified in all lowercase characters, but are matched case-insensitively. To add multiple methods to one rule, use the vertical bar |
as a separator.
此修饰符将规则范围限制为使用指定 HTTP 方法集的请求。允许否定方法。方法必须全部以小写字符指定,但匹配时不区分大小写。要将多种方法添加到一条规则,请使用竖线|
作为分隔符。
Examples 示例
||evil.com^$method=get|head
blocks only GET and HEAD requests toevil.com
.||evil.com^$method=get|head
仅阻止对evil.com
GET 和 HEAD 请求。||evil.com^$method=~post|~put
blocks any requests toevil.com
except POST or PUT.||evil.com^$method=~post|~put
会阻止对evil.com
的任何请求(POST 或 PUT 除外)。@@||evil.com$method=get
unblocks only GET requests toevil.com
.@@||evil.com$method=get
仅解除阻止对evil.com
的 GET 请求。@@||evil.com$method=~post
unblocks any requests toevil.com
except POST.@@||evil.com$method=~post
取消阻止除 POST 之外的任何对evil.com
的请求。
Rules with mixed negated and not negated values are considered invalid.
So, for example, the rule ||evil.com^$method=get|~head
will be ignored.
具有混合否定值和非否定值的规则被视为无效。因此,例如,规则||evil.com^$method=get|~head
将被忽略。
Rules with $method
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.12 or later, and AdGuard Browser Extension for Chrome, Firefox, and Edge with TSUrlFilter v2.1.1 or later.
带$method
修饰符的规则受具有CoreLibs v1.12 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及具有TSUrlFilter v2.1.1 或更高版本的适用于 Chrome、Firefox 和 Edge 的 AdGuard 浏览器扩展支持。
$popup
AdGuard will try to close the browser tab with any address that matches a blocking rule with this modifier. Please note that not all the tabs can be closed.
AdGuard 将尝试关闭具有此修饰符的阻止规则匹配的任何地址的浏览器选项卡。请注意,并非所有选项卡都可以关闭。
Examples 示例
||domain.com^$popup
— if you try to go tohttp://domain.com/
from any page in the browser, a new tab in which specified site has to be opened will be closed by this rule.||domain.com^$popup
— 如果您尝试从浏览器中的任何页面访问http://domain.com/
,则此规则将关闭必须打开指定站点的新选项卡。
$popup
modifier limitations
$popup
修饰符限制
- The
$popup
modifier works best in AdGuard Browser Extension for Chromium-based browsers and Firefox.$popup
修饰符在基于 Chromium 的浏览器和 Firefox 的 AdGuard 浏览器扩展中效果最佳。 - In AdGuard for Chrome MV3 rules with the
$popup
modifier would not work, so we disable converting them to declarative rules. We will try to use them only in our TSUrlFilter engine and close new tabs programmatically.
在AdGuard for Chrome MV3中,带有$popup
修饰符的规则不起作用,因此我们禁止将它们转换为声明性规则。我们将尝试仅在TSUrlFilter引擎中使用它们,并以编程方式关闭新选项卡。 - In AdGuard for iOS and AdGuard for Safari,
$popup
rules simply block the page right away.
在 AdGuard for iOS 和 AdGuard for Safari 中,$popup
规则只是立即阻止页面。 - In AdGuard for Windows, AdGuard for Mac, and AdGuard for Android, the
$popup
modifier may not detect a popup in some cases and it will not be blocked. The$popup
modifier applies thedocument
content type with a special flag which is passed to a blocking page. Blocking page itself can do some checks and close the window if it is really a popup. Otherwise, page should be loaded. It can be combined with other request type modifiers, such as$third-party
,$strict-third-party
,$strict-first-party
, and$important
.
在 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 中,$popup
修饰符在某些情况下可能无法检测到弹出窗口,并且不会被阻止。$popup
修饰符应用带有特殊标志的document
内容类型,该标志被传递到阻塞页面。阻止页面本身可以进行一些检查,如果确实是弹出窗口,则关闭窗口。否则,应该加载页面。它可以与其他请求类型修饰符结合使用,例如$third-party
、$strict-third-party
、$strict-first-party
和$important
。
Rules with the $popup
modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有$popup
修饰符的规则。
$strict-first-party
Works the same as the $~third-party
modifier, but only treats the request as first-party if the referrer and origin have exactly the same hostname.
与$~third-party
修饰符的工作方式相同,但仅当引荐来源网址和来源具有完全相同的主机名时才将请求视为第一方。
Examples 示例
- domain.com$strict-first-party' — this rule applies only to
domain.com
. For example, a request fromdomain.com
tohttp://domain.com/icon.ico
is a first-party request. A request fromsub.domain.com
tohttp://domain.com/icon.ico
is treated as a third-party one (as opposed to the$~third-party
modifier).
domain.com$strict-first-party' — 此规则仅适用于domain.com
。例如,从domain.com
到http://domain.com/icon.ico
的请求是第一方请求。从sub.domain.com
到http://domain.com/icon.ico
的请求被视为第三方请求(而不是$~third-party
修饰符)。
You can use a shorter name (alias) instead of using the full modifier name: $strict1p
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $strict1p
。
$strict-third-party
Works the same as the $third-party
modifier but also treats requests from the domain to its subdomains and vice versa as third-party requests.
与$third-party
修饰符的工作方式相同,但也将从域到其子域的请求视为第三方请求,反之亦然。
Examples 示例
||domain.com^$strict-third-party
— this rule applies to all domains exceptdomain.com
. An example of a third-party request:http://sub.domain.com/banner.jpg
(as opposed to the$third-party
modifier).
||domain.com^$strict-third-party
— 此规则适用于除domain.com
之外的所有域。第三方请求的示例:http://sub.domain.com/banner.jpg
(与$third-party
修饰符相对)。
You can use a shorter name (alias) instead of using the full modifier name: $strict3p
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $strict3p
。
$third-party
A restriction on third-party and custom requests. A third-party request is a request from an external domain. For example, a request to example.org
from domain.com
is a third-party request.
对第三方和自定义请求的限制。第三方请求是来自外部域的请求。例如,从domain.com
向example.org
发出的请求就是第三方请求。
To be considered as such, a third-party request should meet one of the following conditions:
要被视为此类请求,第三方请求应满足以下条件之一:
- Its referrer is not a subdomain of the target domain or vice versa. For example, a request to
subdomain.example.org
fromexample.org
is not a third-party request
它的引荐来源网址不是目标域的子域,反之亦然。例如,从example.org
到subdomain.example.org
的请求不是第三方请求 - Its
Sec-Fetch-Site
header is set tocross-site
其Sec-Fetch-Site
标头设置为cross-site
Examples 示例
$third-party
:$third-party
:
||domain.com^$third-party
— this rule applies to all domains, exceptdomain.com
and its subdomains. An example of a third-party request:http://example.org/banner.jpg
.||domain.com^$third-party
— 此规则适用于所有域,domain.com
及其子域除外。第三方请求的示例:http:http://example.org/banner.jpg
。
If there is a $~third-party
modifier, the rule is only applied to the requests that are not from third parties. Which means, they have to be sent from the same domain.
如果有$~third-party
修饰符,则该规则仅适用于非第三方的请求。这意味着,它们必须从同一域发送。
$~third-party
:$~third-party
:
||domain.com$~third-party
— this rule is applied exclusively todomain.com
. Example of a non third-party request:http://domain.com/icon.ico
.||domain.com$~third-party
— 此规则仅适用于domain.com
。非第三方请求示例:http:http://domain.com/icon.ico
。
You may use a shorter name (alias) instead of using the full modifier name: $3p
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $3p
。
$to
$to
limits the rule scope to requests made to the specified domains and their subdomains. To add multiple domains to one rule, use the |
character as a separator.$to
将规则范围限制为对指定域及其子域发出的请求。要将多个域添加到一条规则,请使用|
字符作为分隔符。
Examples 示例
/ads$to=evil.com|evil.org
blocks any request toevil.com
orevil.org
and their subdomains with a path matching/ads
./ads$to=evil.com|evil.org
阻止任何对evil.com
或evil.org
及其子域的请求,其路径与/ads
匹配。/ads$to=~not.evil.com|evil.com
blocks any request toevil.com
and its subdomains, with a path matching/ads
, except requests tonot.evil.com
and its subdomains.
/ads$to=~not.evil.com|evil.com
阻止任何路径与/ads
匹配的对evil.com
及其子域的请求,对not.evil.com
及其子域的请求除外。/ads$to=~good.com|~good.org
blocks any request with a path matching/ads
, except requests togood.com
orgood.org
and their subdomains./ads$to=~good.com|~good.org
阻止路径与/ads
匹配的任何请求,但对good.com
或good.org
及其子域的请求除外。
$denyallow
cannot be used together with $to
. It can be expressed with inverted $to
: $denyallow=a.com|b.com
is equivalent to $to=~a.com|~b.com
.$denyallow
不能与$to
一起使用。它可以用倒置的$to
表示: $denyallow=a.com|b.com
相当于$to=~a.com|~b.com
。
Rules with the $to
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.12 or later, and AdGuard Browser Extension with TSUrlFilter v2.1.3 or later.
使用CoreLibs v1.12 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及带有TSUrlFilter v2.1.3 或更高版本的 AdGuard 浏览器扩展支持带有$to
修饰符的规则。
Content-type modifiers 内容类型修饰符
There is a set of modifiers, which can be used to limit the rule's application area to certain type of content. These modifiers can also be combined to cover, for example, both images and scripts.
有一组修饰符,可用于将规则的应用范围限制为特定类型的内容。这些修饰符还可以组合起来以覆盖例如图像和脚本。
There is a big difference in how AdGuard determines the content type on different platforms.
For AdGuard Browser Extension, content type for every request is provided by the browser.
AdGuard 在不同平台上确定内容类型的方式存在很大差异。
对于 AdGuard 浏览器扩展,每个请求的内容类型均由浏览器提供。
AdGuard for Windows, Mac, and Android use the following method:
first, the apps try to determine the type of the request by the Sec-Fetch-Dest
request header or by the filename extension.
If the request is not blocked at this stage,
the type will be determined using the Content-Type
header at the beginning of the server response.
适用于 Windows、Mac 和 Android 的 AdGuard 使用以下方法:
首先,应用程序尝试通过Sec-Fetch-Dest
请求标头或文件扩展名来确定请求的类型。如果在此阶段请求未被阻止,则将使用服务器响应开头的Content-Type
标头来确定类型。
Examples of content-type modifiers
内容类型修饰符的示例
||example.org^$image
— corresponds to all images fromexample.org
.||example.org^$image
— 对应于example.org
中的所有图像。||example.org^$script,stylesheet
— corresponds to all the scripts and styles fromexample.org
.
||example.org^$script,stylesheet
— 对应于example.org
中的所有脚本和样式。||example.org^$~image,~script,~stylesheet
— corresponds to all requests toexample.org
except for the images, scripts and styles.
||example.org^$~image,~script,~stylesheet
— 对应于对example.org
的所有请求,图像、脚本和样式除外。
Modifier \ Products 改性剂\产品 | CoreLibs apps CoreLibs 应用程序 | AdGuard for Chromium 适用于 Chromium 的 AdGuard | AdGuard for Chrome MV3 适用于 Chrome 的 AdGuard MV3 | AdGuard for Firefox 适用于 Firefox 的 AdGuard | AdGuard for iOS iOS 版 AdGuard | AdGuard for Safari 适用于 Safari 的 AdGuard | AdGuard Content Blocker AdGuard 内容拦截器 |
---|---|---|---|---|---|---|---|
$document $文档 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$font $字体 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$image $图像 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$media $媒体 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$object $对象 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$other $其他 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$ping | ✅ *[1] | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
$script $脚本 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$stylesheet $样式表 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$subdocument $子文档 | ✅ *[2] | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$websocket | ✅ | ✅ | ✅ | ✅ | ✅ *[3] | ✅ *[3] | ❌ |
$xmlhttprequest $xmlhttp请求 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$webrtc 🚫 $webrtc🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$object-subrequest 🚫 $对象子请求🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
- ✅ — fully supported ✅ — 完全支持
- ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
✅ * — 支持,但可靠性可能会有所不同或可能会出现限制;检查修改器描述以获取更多详细信息 - ❌ — not supported ❌ — 不支持
- 🚫 — removed and no longer supported
🚫 — 已删除且不再受支持
$document
The rule corresponds to the main frame document requests, i.e. HTML documents that are loaded in the browser tab. It does not match iframes, there is a $subdocument
modifier for these.
该规则对应于主框架文档请求,即在浏览器选项卡中加载的 HTML 文档。它与 iframe 不匹配,有一个$subdocument
修饰符。
By default, AdGuard does not block the requests that are loaded in the browser tab (e.g. "main frame bypass"). The idea is not to prevent pages from loading as the user clearly indicated that they want this page to be loaded. However, if the $document
modifier is specified explicitly, AdGuard does not use that logic and prevents the page load. Instead, it responds with a "blocking page".
默认情况下,AdGuard 不会阻止浏览器选项卡中加载的请求(例如“主机绕过”)。这个想法并不是阻止页面加载,因为用户明确表示他们希望加载此页面。但是,如果显式指定$document
修饰符,AdGuard 不会使用该逻辑并阻止页面加载。相反,它以“阻止页面”响应。
If this modifier is used with an exclusion rule (@@
), it completely disables blocking on corresponding pages. It is equivalent to using $elemhide
, $content
, $urlblock
, $jsinject
, $extension
modifiers simultaneously.
如果此修饰符与排除规则 ( @@
) 一起使用,则会完全禁用相应页面上的阻止。它相当于同时使用$elemhide
、 $content
、 $urlblock
、 $jsinject
、 $extension
修饰符。
Examples 示例
@@||example.com^$document
completely disables filtering on all pages atexample.com
and all subdomains.@@||example.com^$document
完全禁用对example.com
和所有子域的所有页面的过滤。||example.com^$document
blocks HTML document request toexample.com
with a blocking page.||example.com^$document
使用阻止页面阻止对example.com
HTML 文档请求。||example.com^$document,redirect=noopframe
redirects HTML document request toexample.com
to an empty html document.
||example.com^$document,redirect=noopframe
将对example.com
HTML 文档请求重定向到空 html 文档。||example.com^$document,removeparam=test
removestest
query parameter from HTML document request toexample.com
.
||example.com^$document,removeparam=test
从对example.com
的 HTML 文档请求中删除test
查询参数。||example.com^$document,replace=/test1/test2/
replacestest1
withtest2
in HTML document request toexample.com
.
||example.com^$document,replace=/test1/test2/
在对example.com
的 HTML 文档请求中将test1
替换为test2
。
You may use a shorter name (alias) instead of using the full modifier name: $doc
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $doc
。
$font
The rule corresponds to requests for fonts, e.g. .woff
filename extension.
该规则对应于字体请求,例如.woff
文件扩展名。
$image
The rule corresponds to images requests.
该规则对应于图像请求。
$media
The rule corresponds to requests for media files — music and video, e.g. .mp4
files.
该规则对应于对媒体文件(音乐和视频,例如.mp4
文件)的请求。
$object
The rule corresponds to browser plugins resources, e.g. Java or Flash.
该规则对应于浏览器插件资源,例如Java 或Flash。
$other
The rule applies to requests for which the type has not been determined or does not match the types listed above.
该规则适用于类型尚未确定或与上面列出的类型不匹配的请求。
$ping
The rule corresponds to requests caused by either navigator.sendBeacon()
or the ping
attribute on links.
该规则对应于由navigator.sendBeacon()
或链接上的ping
属性引起的请求。
$ping
modifier limitations
$ping
修饰符限制
AdGuard for Windows, Mac, and Android often cannot accurately detect navigator.sendBeacon()
.
Using $ping
is not recommended in the filter lists that are supposed to be used by CoreLibs-based AdGuard products.
适用于 Windows、Mac 和 Android 的 AdGuard 通常无法准确检测navigator.sendBeacon()
。不建议在基于 CoreLibs 的 AdGuard 产品应该使用的过滤器列表中使用$ping
。
Rules with $ping
modifier are not supported by AdGuard for Safari and AdGuard for iOS.
AdGuard for Safari 和 AdGuard for iOS 不支持带有$ping
修饰符的规则。
$script
The rule corresponds to script requests, e.g. javascript, vbscript.
该规则对应于脚本请求,例如javascript、vbscript。
$stylesheet
The rule corresponds to CSS files requests.
该规则对应于 CSS 文件请求。
You may use a shorter name (alias) instead of using the full modifier name: $css
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $css
。
$subdocument
The rule corresponds to requests for built-in pages — HTML tags frame
and iframe
.
该规则对应于对内置页面的请求 - HTML 标签frame
和iframe
。
Examples 示例
||example.com^$subdocument
blocks built-in page requests (frame
andiframe
) toexample.com
and all its subdomains anywhere.||example.com^$subdocument
阻止对example.com
及其所有子域的内置页面请求(frame
和iframe
)。||example.com^$subdocument,domain=domain.com
blocks built-in page requests (frame
иiframe
) toexample.com
(and its subdomains) fromdomain.com
and all its subdomains.
||example.com^$subdocument,domain=domain.com
阻止从domain.com
及其所有子域到example.com
(及其子域)的内置页面请求(frame
和iframe
)。
You may use a shorter name (alias) instead of using the full modifier name: $frame
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $frame
。
$subdocument
modified limitations
$subdocument
修改限制
In AdGuard for Windows, Mac, and Android subdocuments are being detected by the Sec-Fetch-Dest header if it is present.
Otherwise, some main pages may be treated as subdocuments.
在 AdGuard for Windows、Mac 和 Android 中,Sec-Fetch-Dest 标头会检测子文档(如果存在)。否则,某些主页可能会被视为子文档。
Rules with $subdocument
modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有$subdocument
修饰符的规则。
$websocket
The rule applies only to WebSocket connections.
该规则仅适用于 WebSocket 连接。
$websocket
modifier limitations
$websocket
修饰符限制
For AdGuard for Safari and AdGuard for iOS, it is supported on devices
with macOS Monterey (version 12) and iOS 16 or higher respectively.
对于 AdGuard for Safari 和 AdGuard for iOS,分别在装有 macOS Monterey(版本 12)和 iOS 16 或更高版本的设备上受支持。
$websocket
modifier is supported in all AdGuard products except AdGuard Content Blocker.
除了 AdGuard Content Blocker 之外,所有 AdGuard 产品均支持$websocket
修饰符。
$xmlhttprequest
The rule applies only to ajax requests (requests sent via javascript object XMLHttpRequest
).
该规则仅适用于 ajax 请求(通过 javascript 对象XMLHttpRequest
发送的请求)。
You may use a shorter name (alias) instead of using the full modifier name: $xhr
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $xhr
。
AdGuard for Windows, Mac, Android when filtering older browsers cannot accurately detect this type and sometimes detects it as $other
or $script
. They can only reliably detect this content type when filtering modern browsers that support Fetch metadata request headers.
AdGuard for Windows、Mac、Android 在过滤旧版浏览器时无法准确检测此类型,有时会将其检测为$other
或$script
。他们只能在过滤支持Fetch 元数据请求标头的现代浏览器时才能可靠地检测到此内容类型。
$object-subrequest
(removed)
$object-subrequest
(已删除)
$object-subrequest
modifier is removed and is no longer supported. Rules with it are considered as invalid. The rule corresponds to requests by browser plugins (it is usually Flash).$object-subrequest
修饰符已删除并且不再受支持。带有它的规则被认为是无效的。该规则对应于浏览器插件(通常是Flash)的请求。
$webrtc
(removed)
$webrtc
(已删除)
The rule applies only to WebRTC connections.
该规则仅适用于 WebRTC 连接。
Examples 示例
||example.com^$webrtc,domain=example.org
blocks webRTC connections toexample.com
fromexample.org
.
||example.com^$webrtc,domain=example.org
阻止从example.org
到example.com
webRTC 连接。@@*$webrtc,domain=example.org
disables the RTC wrapper forexample.org
.@@*$webrtc,domain=example.org
禁用example.org
的 RTC 包装器。
Exception rules modifiers
异常规则修饰符
Exception rules disable the other basic rules for the addresses to which they correspond. They begin with a @@
mark. All the basic modifiers listed above can be applied to them and they also have a few special modifiers.
例外规则禁用它们对应的地址的其他基本规则。它们以@@
标记开头。上面列出的所有基本修饰符都可以应用于它们,并且它们还有一些特殊修饰符。
We recommend to get acquainted with the Adblock Plus filter cheatsheet, for better understanding of how exception rules should be made.
我们建议您熟悉Adblock Plus 过滤器备忘单,以便更好地了解如何制定例外规则。
- ✅ — fully supported ✅ — 完全支持
- ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
✅ * — 支持,但可靠性可能会有所不同或可能会出现限制;检查修改器描述以获取更多详细信息 - ❌ — not supported ❌ — 不支持
$content
Disables HTML filtering, $hls
, $replace
, and $jsonprune
rules on the pages that match the rule.
在与规则匹配的页面上禁用HTML 过滤、 $hls
、 $replace
和$jsonprune
规则。
Examples 示例
@@||example.com^$content
disables all content modifying rules on pages atexample.com
and all its subdomains.@@||example.com^$content
禁用example.com
及其所有子域页面上的所有内容修改规则。
$elemhide
Disables any cosmetic rules on the pages matching the rule.
禁用与规则匹配的页面上的任何修饰规则。
Examples 示例
@@||example.com^$elemhide
disables all cosmetic rules on pages atexample.com
and all subdomains.@@||example.com^$elemhide
禁用example.com
和所有子域页面上的所有修饰规则。
You may use a shorter name (alias) instead of using the full modifier name: $ehide
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $ehide
。
$extension
Disables specific userscripts or all userscripts for a given domain.
禁用给定域的特定用户脚本或所有用户脚本。
Syntax 句法
$extension[="userscript_name1"[|"userscript_name2"[|"userscript_name3"[...]]]]
userscript_name(i)
stands for a specific userscript name to be disabled by the modifier. The modifier can contain any number of userscript names or none. In the latter case the modifier disables all the userscripts.userscript_name(i)
代表要被修饰符禁用的特定用户脚本名称。修饰符可以包含任意数量的用户脚本名称,也可以不包含。在后一种情况下,修饰符将禁用所有用户脚本。
Userscript names usually contain spaces or other special characters, which is why you should enclose the name in quotes. Both single ('
) and double ("
) ASCII quotes are supported. Multiple userscript names should be separated with a pipe (|
). However, if a userscript name is a single word without any special characters, it can be used without quotes.
用户脚本名称通常包含空格或其他特殊字符,这就是为什么您应该将名称括在引号中。支持单 ( '
) 和双 ( "
) ASCII 引号。多个用户脚本名称应使用竖线 ( |
) 分隔。但是,如果用户脚本名称是没有任何特殊字符的单个单词,则可以不使用引号。
You can also exclude a userscript by adding a ~
character before it. In this case, the userscript will not be disabled by the modifier.
您还可以通过在用户脚本前添加~
字符来排除用户脚本。在这种情况下,用户脚本不会被修改器禁用。
$extension=~"userscript name"
When excluding a userscript, you must place ~
outside the quotes.
排除用户脚本时,必须将~
放在引号之外。
If a userscript's name includes quotes ("
), commas (,
), or pipes (|
), they must be escaped with a backslash (\
).
如果用户脚本的名称包含引号 ( "
)、逗号 ( ,
) 或竖线 ( |
),则必须使用反斜杠 ( \
) 对它们进行转义。
$extension="userscript name\, with \"quote\""
Examples 示例
@@||example.com^$extension="AdGuard Assistant"
disables theAdGuard Assistant
userscript onexample.com
website.
@@||example.com^$extension="AdGuard Assistant"
禁用example.com
网站上的AdGuard Assistant
脚本。@@||example.com^$extension=MyUserscript
disables theMyUserscript
userscript onexample.com
website.
@@||example.com^$extension=MyUserscript
禁用example.com
网站上的MyUserscript
用户脚本。@@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker'
disables bothAdGuard Assistant
andAdGuard Popup Blocker
userscripts onexample.com
website.
@@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker'
禁用example.com
网站上的AdGuard Assistant
和AdGuard Popup Blocker
用户脚本。@@||example.com^$extension=~"AdGuard Assistant"
disables all user scripts onexample.com
website, exceptAdGuard Assistant
.
@@||example.com^$extension=~"AdGuard Assistant"
禁用example.com
网站上的所有用户脚本AdGuard Assistant
除外)。@@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker"
disables all user scripts onexample.com
website, exceptAdGuard Assistant
andAdGuard Popup Blocker
.
@@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker"
禁用example.com
网站上的所有用户脚本,除了AdGuard Assistant
和AdGuard Popup Blocker
。@@||example.com^$extension
no userscript will work on webpages onexample.com
.@@||example.com^$extension
任何用户脚本都无法在example.com
上的网页上运行。@@||example.com^$extension="AdGuard \"Assistant\""
disables theAdGuard "Assistant"
userscript onexample.com
website.
@@||example.com^$extension="AdGuard \"Assistant\""
禁用example.com
网站上的AdGuard "Assistant"
用户脚本。
- Only AdGuard for Windows, Mac, Android are technically capable of using rules with
$extension
modifier.
从技术上讲,只有适用于 Windows、Mac、Android 的 AdGuard 能够使用带有$extension
修饰符的规则。 - Rules with
$extension
modifier with specific userscript name are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.13 or later.
AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android(带有CoreLibs v1.13 或更高版本)支持带有$extension
修饰符和特定用户脚本名称的规则。
$jsinject
Forbids adding of JavaScript code to the page. You can read about scriptlets and javascript rules further.
禁止向页面添加 JavaScript 代码。您可以进一步阅读有关 scriptlet 和 javascript 规则的内容。
Examples 示例
@@||example.com^$jsinject
disables javascript on pages atexample.com
and all subdomains.@@||example.com^$jsinject
禁用example.com
和所有子域页面上的 javascript。
$jsinject
modifier limitations
$jsinject
修饰符限制
Rules with the $jsinject
modifier cannot be converted to DNR in AdGuard for Chrome MV3.
We only use them in the TSUrlFilter engine to disable some cosmetic rules.
带有$jsinject
修饰符的规则无法在AdGuard for Chrome MV3中转换为 DNR。我们仅在TSUrlFilter引擎中使用它们来禁用某些修饰规则。
$stealth
Disables the Tracking protection (formerly Stealth Mode) module for all corresponding pages and requests.
禁用所有相应页面和请求的跟踪保护(以前称为隐形模式)模块。
Syntax 句法
$stealth [= opt1 [| opt2 [| opt3 [...]]]]
opt(i)
stand for certain Tracking protection options disabled by the modifier.
The modifier can contain any number of specific options (see below) or none.
In the latter case the modifier disables all the Tracking protection features.opt(i)
代表由修饰符禁用的某些跟踪保护选项。修饰符可以包含任意数量的特定选项(见下文)或不包含。在后一种情况下,修改器将禁用所有跟踪保护功能。
The list of the available modifier options:
可用修饰符选项列表:
searchqueries
disables Hide your search queries optionsearchqueries
禁用隐藏您的搜索查询选项donottrack
disables Ask websites not to track you optiondonottrack
禁用“要求网站不要跟踪您”选项3p-cookie
disables Self-destructing third-party cookies option3p-cookie
禁用自毁第三方 cookie选项1p-cookie
disables Self-destructing first-party cookies option1p-cookie
禁用自毁第一方 cookie选项3p-cache
disables Disable cache for third-party requests option3p-cache
禁用禁用第三方请求缓存选项3p-auth
disables Block third-party Authorization header option3p-auth
禁用阻止第三方授权标头选项webrtc
disables Block WebRTC optionwebrtc
禁用阻止 WebRTC选项push
disables Block Push API optionpush
禁用Block Push API选项location
disables Block Location API optionlocation
禁用阻止位置 API选项flash
disables Block Flash optionflash
禁用Block Flash选项java
disables Block Java optionjava
禁用Block Java选项referrer
disables Hide Referer from third parties optionreferrer
禁用隐藏第三方选项的推荐人useragent
disables Hide your User-Agent optionuseragent
禁用隐藏您的用户代理选项ip
disables Hide your IP address optionip
禁用隐藏您的 IP 地址选项xclientdata
disables Remove X-Client-Data header from HTTP requests optionxclientdata
禁用“从 HTTP 请求中删除 X-Client-Data 标头”选项dpi
disables Protect from DPI optiondpi
禁用DPI 保护选项
Examples 示例
@@||example.com^$stealth
disables Tracking protection forexample.com
(and subdomains) requests, except for blocking cookies and hiding tracking parameters (see below).@@||example.com^$stealth
禁用对example.com
(和子域)请求的跟踪保护,但阻止 cookie 和隐藏跟踪参数除外(见下文)。@@||domain.com^$script,stealth,domain=example.com
disables Tracking protection only for script requests todomain.com
(and its subdomains) onexample.com
and all its subdomains.
@@||domain.com^$script,stealth,domain=example.com
仅对example.com
及其所有子域上的domain.com
(及其子域)的脚本请求禁用跟踪保护。@@||example.com^$stealth=3p-cookie|dpi
disables blocking third-party cookies and DPI fooling measures forexample.com
.
@@||example.com^$stealth=3p-cookie|dpi
禁用对example.com
的第三方 cookie 和 DPI 欺骗措施的阻止。
Blocking cookies and removing tracking parameters is achieved by using rules with the $cookie
, $urltransform
and $removeparam
modifiers. Exception rules that contain only the $stealth
modifier will not do these things. If you want to completely disable all Tracking protection features for a given domain, you must include all three modifiers: @@||example.org^$stealth,removeparam,cookie
.
阻止 cookie 和删除跟踪参数是通过使用带有$cookie
、 $urltransform
和$removeparam
修饰符的规则来实现的。仅包含$stealth
修饰符的异常规则不会执行这些操作。如果要完全禁用给定域的所有跟踪保护功能,则必须包含所有三个修饰符: @@||example.org^$stealth,removeparam,cookie
。
- Modifier options must be lowercase, i.e.
$stealth=DPI
will be rejected.
修饰符选项必须是小写,即$stealth=DPI
将被拒绝。 - Modifier options cannot be negated, i.e.
$stealth=~3p-cookie
will be rejected.
修饰符选项不能被否定,即$stealth=~3p-cookie
将被拒绝。 - AdGuard Browser Extension supports only
searchqueries
,donottrack
,referrer
,xclientdata
,1p-cookie
and3p-cookie
options.
AdGuard 浏览器扩展仅支持searchqueries
、donottrack
、referrer
、xclientdata
、1p-cookie
和3p-cookie
选项。
- Tracking protection (formerly Stealth Mode) is available in AdGuard for Windows, AdGuard for Mac,
AdGuard for Android, and AdGuard Browser Extension for Firefox and Chromium-based browsers, except AdGuard for Chrome MV3.
All other products will ignore the rules with
$stealth
modifier.
跟踪保护(以前称为隐秘模式)适用于 Windows 版 AdGuard、Mac 版 AdGuard、Android 版 AdGuard 以及 Firefox 和基于 Chromium 的浏览器的 AdGuard 浏览器扩展(AdGuard for Chrome MV3 除外)。所有其他产品将忽略带有$stealth
修饰符的规则。 - Rules with
$stealth
modifier with specific options are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.10 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
具有特定选项的$stealth
修饰符的规则受带有 CoreLibs v1.10 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android with CoreLibs v1.10 或更高版本以及带有TSUrlFilter v3.0.0 或更高版本的 AdGuard 浏览器扩展的支持。
$urlblock
Disables blocking of all requests sent from the pages matching the rule and disables all $cookie
rules.
禁用对从匹配规则的页面发送的所有请求的阻止,并禁用所有$cookie
规则。
Examples 示例
@@||example.com^$urlblock
— any requests sent from the pages atexample.com
and all subdomains are not going to be blocked.@@||example.com^$urlblock
— 从example.com
页面和所有子域发送的任何请求都不会被阻止。
$urlblock
modifier limitations
$urlblock
修饰符限制
In AdGuard for iOS and AdGuard for Safari, rules with $urlblock
work
as $document exclusion — unblock everything.
在 AdGuard for iOS 和 AdGuard for Safari 中,带有$urlblock
规则充当$document 排除— 解锁所有内容。
Rules with $urlblock
modifier are not supported by AdGuard Content Blocker,
and AdGuard for Chrome MV3.
AdGuard 内容拦截器和 AdGuard for Chrome MV3 不支持带有$urlblock
修饰符的规则。
Generic rules 通用规则
Before we can proceed to the next modifiers, we have to make a definition of generic rules. The rule is generic if it is not limited to specific domains.
Wildcard character *
is supported as well.
在我们继续进行下一个修饰符之前,我们必须定义通用规则。如果该规则不限于特定域,则该规则是通用的。还支持通配符*
。
For example, these rules are generic:
例如,这些规则是通用的:
###banner
*###banner
#@#.adsblock
*#@#.adsblock
~domain.com###banner
||domain.com^
||domain.com^$domain=~example.com
And these are not: 这些不是:
domain.com###banner
||domain.com^$domain=example.com
$genericblock
Disables generic basic rules on pages that correspond to exception rule.
禁用与例外规则对应的页面上的通用基本规则。
Examples 示例
@@||example.com^$genericblock
disables generic basic rules on any pages atexample.com
and all subdomains.@@||example.com^$genericblock
禁用example.com
和所有子域的任何页面上的通用基本规则。
$genericblock
modifier limitations
$genericblock
修饰符限制
In AdGuard for iOS and AdGuard for Safari, rules with $genericblock
work
as $document exclusion — unblock everything.
在 AdGuard for iOS 和 AdGuard for Safari 中,带有$genericblock
规则充当$document 排除— 解锁所有内容。
Rules with $genericblock
modifier are not supported by AdGuard Content Blocker,
and AdGuard for Chrome MV3.
AdGuard 内容拦截器和 AdGuard for Chrome MV3 不支持带有$genericblock
修饰符的规则。
$generichide
Disables all generic cosmetic rules on pages that correspond to the exception rule.
禁用与例外规则对应的页面上的所有通用修饰规则。
Examples 示例
@@||example.com^$generichide
disables generic cosmetic rules on any pages atexample.com
and its subdomains.@@||example.com^$generichide
禁用example.com
及其子域的任何页面上的通用修饰规则。
You may use a shorter name (alias) instead of using the full modifier name: $ghide
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $ghide
。
specifichide
Disables all specific element hiding and CSS rules, but not general ones. Has an opposite effect to $generichide
.
禁用所有特定元素隐藏和 CSS 规则,但不禁用一般规则。与$generichide
具有相反的效果。
Examples 示例
@@||example.org^$specifichide
disablesexample.org##.banner
but not##.banner
.@@||example.org^$specifichide
禁用example.org##.banner
但不禁用##.banner
。
You may use a shorter name (alias) instead of using the full modifier name: $shide
.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $shide
。
All cosmetic rules — not just specific ones — can be disabled by $elemhide
modifier.
所有修饰规则(不仅仅是特定的规则)都可以通过$elemhide
修饰符禁用。
Rules with $specifichide
modifier are not supported by AdGuard for iOS, AdGuard for Safari, and AdGuard Content Blocker.
AdGuard for iOS、AdGuard for Safari 和 AdGuard Content Blocker 不支持带有$specifichide
修饰符的规则。
Advanced capabilities 先进的功能
These modifiers are able to completely change the behavior of basic rules.
这些修饰符能够完全改变基本规则的行为。
Modifier \ Products 改性剂\产品 | CoreLibs apps CoreLibs 应用程序 | AdGuard for Chromium 适用于 Chromium 的 AdGuard | AdGuard for Chrome MV3 适用于 Chrome 的 AdGuard MV3 | AdGuard for Firefox 适用于 Firefox 的 AdGuard | AdGuard for iOS iOS 版 AdGuard | AdGuard for Safari 适用于 Safari 的 AdGuard | AdGuard Content Blocker AdGuard 内容拦截器 |
---|---|---|---|---|---|---|---|
$all $全部 | ✅ | ✅ | ✅ *[1] | ✅ | ✅ | ✅ | ❌ |
$badfilter $坏过滤器 | ✅ | ✅ | ✅ *[2] | ✅ | ✅ | ✅ | ❌ |
$cookie | ✅ | ✅ | ✅ *[3] | ✅ | ❌ | ❌ | ❌ |
$csp | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$hls | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$inline-font $内联字体 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$inline-script $内联脚本 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$jsonprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$xmlprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$network $网络 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$permissions $权限 | ✅ *[4] | ✅ | ✅ | ✅ *[4] | ❌ | ❌ | ❌ |
$redirect $重定向 | ✅ | ✅ | ✅ *[5] | ✅ | ❌ | ❌ | ❌ |
$redirect-rule $重定向规则 | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$referrerpolicy $referrer政策 | ✅ | ❌ | ⏳ | ❌ | ❌ | ❌ | ❌ |
$removeheader $删除标题 | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$removeparam $删除参数 | ✅ | ✅ | ✅ *[6] | ✅ | ❌ | ❌ | ❌ |
$replace $替换 | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
$urltransform $url变换 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
noop 努普 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$empty 👎 $空👎 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$mp4 👎 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — fully supported ✅ — 完全支持
- ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
✅ * — 支持,但可靠性可能会有所不同或可能会出现限制;检查修改器描述以获取更多详细信息 - ⏳ — feature that is planned to be implemented but is not yet available in any product
⏳ — 计划实现但尚未在任何产品中提供的功能 - ❌ — not supported ❌ — 不支持
- 👎 — deprecated; still supported but will be removed in the future
👎 — 已弃用;仍然受支持,但将来会被删除
$all
$all
modifier is made of all content-types modifiers and $popup
.
E.g. rule ||example.org^$all
is converting into rule:$all
修饰符由所有内容类型修饰符和$popup
组成。例如规则||example.org^$all
正在转换为规则:
||example.org^$document,subdocument,font,image,media,object,other,ping,script,stylesheet,websocket,xmlhttprequest,popup
This modifier cannot be used as an exception with the @@
mark.
此修饰符不能与@@
标记一起用作例外。
$all
modifier limitations
$all
修饰符限制
Since $popup
is a part if $all
, the $all
modifier is not supported by AdGuard for Chrome MV3
because of $popup
modifier limitations.
由于$popup
是$all
一部分,因此由于$popup
修饰符的限制, AdGuard for Chrome MV3 不支持$all
修饰符。
Rules with $all
modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有$all
修饰符的规则。
$badfilter
The rules with the $badfilter
modifier disable other basic rules to which they refer. It means that the text of the disabled rule should match the text of the $badfilter
rule (without the $badfilter
modifier).
带有$badfilter
修饰符的规则禁用它们引用的其他基本规则。这意味着禁用规则的文本应与$badfilter
规则的文本匹配(不带$badfilter
修饰符)。
Examples 示例
||example.com$badfilter
disables||example.com
||example.com$badfilter
禁用||example.com
||example.com$image,badfilter
disables||example.com$image
||example.com$image,badfilter
禁用||example.com$image
@@||example.com$badfilter
disables@@||example.com
@@||example.com$badfilter
禁用@@||example.com
||example.com$domain=domain.com,badfilter
disables||example.com$domain=domain.com
||example.com$domain=domain.com,badfilter
禁用||example.com$domain=domain.com
Rules with $badfilter
modifier can disable other basic rules for specific domains if they fulfill the following conditions:
如果具有$badfilter
修饰符的规则满足以下条件,则可以禁用特定域的其他基本规则:
- The rule has a
$domain
modifier
该规则有一个$domain
修饰符 - The rule does not have a negated domain
~
in$domain
modifier value
该规则在$domain
修饰符值中没有否定域~
In that case, the $badfilter
rule will disable the corresponding rule for domains specified in both the $badfilter
and basic rules. Please note that wildcard-TLD logic works here as well.
在这种情况下, $badfilter
规则将禁用$badfilter
和基本规则中指定的域的相应规则。请注意,通配符 TLD 逻辑在这里也适用。
Examples 示例
/some$domain=example.com|example.org|example.io
is disabled forexample.com
by/some$domain=example.com,badfilter
/some$domain=example.com|example.org|example.io
被example.com
禁用/some$domain=example.com,badfilter
/some$domain=example.com|example.org|example.io
is disabled forexample.com
andexample.org
by/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org|example.io
对example.com
和example.org
禁用/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org
and/some$domain=example.io
are disabled completely by/some$domain=example.com|example.org|example.io,badfilter
/some$domain=example.com|example.org
和/some$domain=example.io
被完全禁用/some$domain=example.com|example.org|example.io,badfilter
/some$domain=example.com|example.org|example.io
is disabled completely by/some$domain=example.*,badfilter
/some$domain=example.com|example.org|example.io
被完全禁用/some$domain=example.*,badfilter
/some$domain=example.*
is disabled forexample.com
andexample.org
by/some$domain=example.com|example.org,badfilter
/some$domain=example.*
对example.com
和example.org
禁用/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org|example.io
is NOT disabled forexample.com
by/some$domain=example.com|~example.org,badfilter
because the value of$domain
modifier contains a negated domain
/some$domain=example.com|example.org|example.io
未禁用example.com
/some$domain=example.com|~example.org,badfilter
因为$domain
修饰符的值包含否定域
$badfilter
modifier limitations
$badfilter
修饰符限制
In AdGuard for Chrome MV3 a rule with the $badfilter
modifier is applied in DNR only if it fully cancels the source rule. We cannot calculate it if it is only partially canceled. Examples
在AdGuard for Chrome MV3中,仅当完全取消源规则时,才会在 DNR 中应用带有$badfilter
修饰符的规则。如果只是部分取消的话我们无法计算。示例
Rules with $badfilter
modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有$badfilter
修饰符的规则。
$cookie
The $cookie
modifier completely changes rule behavior. Instead of blocking a request, this modifier makes AdGuard suppress or modify the Cookie
and Set-Cookie
headers.$cookie
修饰符完全改变了规则行为。此修饰符不会阻止请求,而是使 AdGuard 抑制或修改Cookie
和Set-Cookie
标头。
Multiple rules matching a single request
多个规则匹配单个请求
In case if multiple $cookie
rules match a single request, we will apply each of them one by one.
如果多个$cookie
规则与单个请求匹配,我们将一一应用它们。
Syntax 句法
$cookie [= name[; maxAge = seconds [; sameSite = strategy ]]]
where: 在哪里:
name
— optional, string or regular expression to match cookie name.name
— 可选,字符串或正则表达式来匹配 cookie 名称。seconds
— number of seconds for current time to offset the expiration date of cookie.seconds
— 当前时间偏移 cookie 过期日期的秒数。strategy
— string for Same-Site strategy to be applied to the cookie.strategy
— 应用于 cookie 的同站点策略的字符串。
For example, 例如,
||example.org^$cookie=NAME;maxAge=3600;sameSite=lax
every time AdGuard encounters a cookie called NAME
in a request to example.org
, it will do the following:
每次 AdGuard 在对example.org
请求中遇到名为NAME
的 cookie 时,它都会执行以下操作:
- Set its expiration date to current time plus
3600
seconds
将其到期日期设置为当前时间加上3600
秒 - Makes the cookie use Same-Site "lax" strategy.
使 cookie 使用Same-Site “宽松”策略。
Escaping special characters
转义特殊字符
If regular expression name
is used for matching, two characters must be escaped: comma ,
and dollar sign $
. Use backslash \
to escape each of them. For example, escaped comma looks like this: \,
.
如果使用正则表达式name
进行匹配,则必须转义两个字符:逗号,
美元符号$
。使用反斜杠\
来转义它们中的每一个。例如,转义逗号如下所示: \,
。
Examples 示例
||example.org^$cookie
blocks all cookies set byexample.org
; this is an equivalent to settingmaxAge=0
||example.org^$cookie
阻止example.org
设置的所有cookie;这相当于设置maxAge=0
$cookie=__cfduid
blocks CloudFlare cookie everywhere$cookie=__cfduid
到处阻止 CloudFlare cookie$cookie=/__utm[a-z]/
blocks Google Analytics cookies everywhere$cookie=/__utm[az]/
到处阻止 Google Analytics cookie||facebook.com^$third-party,cookie=c_user
prevents Facebook from tracking you even if you are logged in
||facebook.com^$third-party,cookie=c_user
即使您已登录,也会阻止 Facebook 跟踪您
There are two methods to deactivate $cookie
rules: the primary method involves using an exception marked with @@
— @@||example.org^$cookie
. The alternative method employs a $urlblock
exception (also included under the $document
exception alias — $elemhide,jsinject,content,urlblock,extension
).
Here's how it works:
有两种方法可以停用$cookie
规则:主要方法涉及使用标有@@
异常 — @@||example.org^$cookie
。另一种方法采用$urlblock
异常(也包含在$document
异常别名下 - $elemhide,jsinject,content,urlblock,extension
)。它的工作原理如下:
@@||example.org^$cookie
unblocks all cookies set byexample.org
@@||example.org^$cookie
取消阻止example.org
设置的所有 cookie@@||example.org^$urlblock
unblocks all cookies set byexample.org
and disables blocking of all requests sent fromexample.org
@@||example.org^$urlblock
取消阻止example.org
设置的所有 cookie 并禁用阻止阻止从example.org
发送的所有请求@@||example.org^$cookie=concept
unblocks a single cookie namedconcept
@@||example.org^$cookie=concept
解锁单个名为concept
的cookie@@||example.org^$cookie=/^_ga_/
unblocks every cookie that matches the regular expression
@@||example.org^$cookie=/^_ga_/
解除阻止与正则表达式匹配的每个 cookie
$cookie
modifier limitations
$cookie
修饰符限制
In AdGuard for Chrome MV3 we delete cookies in 2 ways: from content-script
side (to which we have access)
and from onBeforeSendHeaders
listener. Since onBeforeSendHeaders
and other listeners are no longer blocking,
we are not able to delete them in all cases.
You can check if a rule works with this test.
在AdGuard for Chrome MV3中,我们通过两种方式删除 cookie:从content-script
端(我们有权访问)和从onBeforeSendHeaders
侦听器。由于onBeforeSendHeaders
和其他侦听器不再阻塞,因此我们无法在所有情况下删除它们。您可以检查规则是否适用于此测试。
$cookie
rules support these types of modifiers: $domain
, $~domain
, $important
, $third-party
, $~third-party
, strict-third-party
, and strict-first-party
.$cookie
规则支持以下类型的修饰符: $domain
、 $~domain
、 $important
、 $third-party
、 $~third-party
、 strict-third-party
和strict-first-party
。
Rules with $cookie
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard for iOS 和 AdGuard for Safari 不支持带有$cookie
修饰符的规则。
$csp
This modifier completely changes the rule behavior. If it is applied to a rule, the rule will not block the matching request. Response headers will be modified instead.
此修饰符完全改变了规则行为。如果应用于规则,则该规则不会阻止匹配的请求。响应标头将被修改。
In order to use this type of rules, it is required to have the basic understanding of the Content Security Policy security layer.
为了使用此类规则,需要对内容安全策略安全层有基本的了解。
For the requests matching a $csp
rule, we will strengthen response security policy by enhancing the content security policy, similar to the content security policy of the $csp
modifier contents. $csp
rules are applied independently from any other rule type. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
对于匹配$csp
规则的请求,我们会通过增强内容安全策略来加强响应安全策略,类似于$csp
修饰符内容的内容安全策略。 $csp
规则的应用独立于任何其他规则类型。只有文档级异常可以影响它(请参阅示例部分),但没有其他基本规则。
Multiple rules matching a single request
多个规则匹配单个请求
In case if multiple $csp
rules match a single request, we will apply each of them.
如果多个$csp
规则与单个请求匹配,我们将应用每个规则。
Syntax 句法
$csp
value syntax is similar to the Content Security Policy header syntax.$csp
值语法类似于内容安全策略标头语法。
$csp
value can be empty in the case of exception rules. See examples section below.
如果有例外规则, $csp
值可以为空。请参阅下面的示例部分。
Examples 示例
||example.org^$csp=frame-src 'none'
blocks all frames on example.org and its subdomains.
||example.org^$csp=frame-src 'none'
阻止 example.org 及其子域上的所有框架。@@||example.org/page/*$csp=frame-src 'none'
disables all rules with the$csp
modifier exactly matchingframe-src 'none'
on all the pages matching the rule pattern. For instance, the rule above.
@@||example.org/page/*$csp=frame-src 'none'
禁用与规则模式匹配的所有页面上的$csp
修饰符与frame-src 'none'
完全匹配的所有规则。例如上面的规则。@@||example.org/page/*$csp
disables all the$csp
rules on all the pages matching the rule pattern.@@||example.org/page/*$csp
禁用与规则模式匹配的所有页面上的所有$csp
规则。||example.org^$csp=script-src 'self' 'unsafe-eval' http: https:
disables inline scripts on all the pages matching the rule pattern.
||example.org^$csp=script-src 'self' 'unsafe-eval' http: https:
禁用与规则模式匹配的所有页面上的内联脚本。@@||example.org^$document
or@@||example.org^$urlblock
disables all the$csp
rules on all the pages matching the rule pattern.@@||example.org^$document
或@@||example.org^$urlblock
禁用所有与规则模式匹配的页面上的所有$csp
规则。
- There are a few characters forbidden in the
$csp
value:,
,$
.$csp
值中禁止使用一些字符:,
,$
。 $csp
rules support three types of modifiers:$domain
,$important
,$subdocument
.$csp
规则支持三种类型的修饰符:$domain
、$important
、$subdocument
。- Rules with
report-*
directives are considered invalid.
带有report-*
指令的规则被认为是无效的。
Rules with $csp
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard for iOS 和 AdGuard for Safari 不支持带有$csp
修饰符的规则。
$hls
$hls
rules modify the response of a matching request. They are intended as a convenient way to remove segments from HLS playlists (RFC 8216).$hls
规则修改匹配请求的响应。它们旨在作为从HLS 播放列表 (RFC 8216)中删除片段的便捷方法。
The word "segment" in this document means either a "Media Segment" or a "playlist" as part of a "Master Playlist": $hls
rules do not distinguish between a "Master Playlist" and a "Media Playlist".
本文档中的“片段”一词表示“媒体片段”或作为“主播放列表”一部分的“播放列表”: $hls
规则不区分“主播放列表”和“媒体播放列表”。
Syntax 句法
||example.org^$hls=urlpattern
removes segments whose URL matches the URL patternurlpattern
. The pattern works just like the one in basic URL rules, however, the characters/
,$
and,
must be escaped with\
insideurlpattern
.||example.org^$hls=urlpattern
删除 URL 与 URL 模式urlpattern
匹配的段。该模式的工作方式与基本 URL 规则中的模式类似,但是字符/
、$
和,
必须在urlpattern
中使用\
进行转义。||example.org^$hls=/regexp/options
removes segments where the URL or one of the tags (for certain options, if present) is matched by the regular expressionregexp
. Availableoptions
are:
||example.org^$hls=/regexp/options
删除 URL 或标签之一(对于某些选项,如果存在)与正则表达式regexp
匹配的段。可用options
有:t
— instead of testing the segment's URL, test each of the segment's tags against the regular expression. A segment with a matching tag is removed;t
— 不是测试段的 URL,而是根据正则表达式测试段的每个标签。删除具有匹配标签的段;i
— make the regular expression case-insensitive.i
— 使正则表达式不区分大小写。
The characters /
, $
and ,
must be escaped with \
inside regexp
.
字符/
、 $
和,
必须在regexp
中使用\
进行转义。
Exceptions 例外情况
Basic URL exceptions shall not disable rules with $hls
modifier. They can be disabled as described below:
基本 URL 例外不得禁用带有$hls
修饰符的规则。可以按如下所述禁用它们:
@@||example.org^$hls
disables all$hls
rules for responses from URLs matching||example.org^
.@@||example.org^$hls
对来自匹配||example.org^
URL 的响应禁用所有$hls
规则。@@||example.org^$hls=text
disables all$hls
rules with the value of the$hls
modifier equal totext
for responses from URLs matching||example.org^
.@@||example.org^$hls=text
禁用所有$hls
规则,其中$hls
修饰符的值等于来自匹配||example.org^
URL 的响应的text
。
$hls
rules can also be disabled by $document
, $content
and $urlblock
exception rules.$hls
规则也可以通过$document
、 $content
和$urlblock
例外规则禁用。
When multiple $hls
rules match the same request, their effect is cumulative.
当多个$hls
规则匹配同一个请求时,它们的效果是累积的。
Examples 示例
||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads
removes all segments with the matching URL.
||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads
删除具有匹配 URL 的所有段。||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i
achieves more or less the same with a regular expression instead of a URL pattern.
||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i
使用正则表达式而不是 URL 模式可以实现或多或少相同的效果。||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
removes all segments which have the matching tag.
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
删除所有具有匹配标签的段。
Anatomy of an HLS playlist
HLS 播放列表剖析
A quick summary of the specification:
规范的快速摘要:
- An HLS playlist is a collection of text lines
HLS 播放列表是文本行的集合 - A line may be empty, a comment (starts with
#
), a tag (also starts with#
, can only be recognized by name) or a URL
一行可以为空、注释(以#
开头)、标签(也以#
开头,只能通过名称识别)或 URL - A URL line is called a "segment"
URL 行称为“段” - Tags may apply to a single segment, i.e. the first URL line after the tag, to all segments following the tag and until the tag with the same name, or to the whole playlist
标签可以应用于单个片段,即标签之后的第一个 URL 行,应用于该标签之后的所有片段,直到具有相同名称的标签,或者应用于整个播放列表
Some points specific to the operation of $hls
rules:$hls
规则操作的一些具体要点:
- When a segment is removed, all of the tags that apply only to that segment are also removed
删除某个段时,仅适用于该段的所有标签也会被删除 - When there is a tag that applies to multiple segments, and all of those segments are removed, the tag is also removed
当一个标签适用于多个段,并且所有这些段都被删除时,该标签也会被删除 - Since there is no way to recognize different kinds of tags by syntax, we recognize all of the tags specified by the RFC, plus some non-standard tags that we have seen in the field. Any lines starting with
#
and not recognized as a tag are passed through without modification, and are not matched against the rules
由于无法通过语法来识别不同类型的标签,因此我们识别 RFC 指定的所有标签,以及我们在该领域看到的一些非标准标签。任何以#
开头且未被识别为标记的行都会不加修改地通过,并且不会与规则匹配 - Tags will not be matched if they apply to the entire playlist, and
$hls
rules cannot be used to remove them, as these rule types are intended for segment removals. If you know what you are doing, you can use$replace
rules to remove or rewrite just a single tag from the playlist
如果标签应用于整个播放列表,则它们不会被匹配,并且$hls
规则不能用于删除它们,因为这些规则类型旨在用于片段删除。如果您知道自己在做什么,则可以使用$replace
规则从播放列表中删除或重写单个标签
An example of a transformation done by the rules:
由规则完成的转换的示例:
Original response 原始回复
Applied rules 应用规则
Modified response 修改后的响应
- Rules with the
$hls
modifier can only be used in trusted filters.
带有$hls
修饰符的规则只能在受信任的过滤器中使用。 $hls
rules are compatible with the modifiers$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and$xmlhttprequest
only.$hls
规则仅与修饰符$domain
、$third-party
、$strict-third-party
、$strict-first-party
、$app
、$important
、$match-case
和$xmlhttprequest
兼容。$hls
rules only apply to HLS playlists, which are UTF-8 encoded text starting with the line#EXTM3U
. Any other response will not be modified by these rules.$hls
规则仅适用于 HLS 播放列表,这些播放列表是以#EXTM3U
行开头的 UTF-8 编码文本。任何其他响应都不会被这些规则修改。$hls
rules do not apply if the size of the original response is more than 10 MB.
如果原始响应的大小超过 10 MB,则$hls
规则不适用。
$inline-script
The $inline-script
modifier is designed to block inline JavaScript embedded into the web page, using Content Security Policy (CSP). It improves security and privacy by preventing application of inline ads or potentially malicious scripts. The rule ||example.org^$inline-script
is converting into the CSP-syntax rule:$inline-script
修饰符旨在使用内容安全策略 (CSP) 阻止嵌入网页的内联 JavaScript。它通过防止应用内嵌广告或潜在的恶意脚本来提高安全性和隐私性。规则||example.org^$inline-script
正在转换为 CSP 语法规则:
||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$inline-font
The $inline-font
modifier is designed to block inline fonts embedded into the web page, using Content Security Policy (CSP). It improves security and privacy by preventing application of inline fonts that could be used for data collection and fingerprinting. The rule ||example.org^$inline-font
is converting into the CSP-syntax rule:$inline-font
修饰符旨在使用内容安全策略 (CSP) 阻止嵌入网页的内联字体。它通过阻止应用可用于数据收集和指纹识别的内联字体来提高安全性和隐私性。规则||example.org^$inline-font
正在转换为 CSP 语法规则:
||example.org^$csp=font-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$jsonprune
$jsonprune
rules modify the response to a matching request by removing JSON items that match a modified
JSONPath expression. They do not modify responses which are not valid JSON documents.$jsonprune
规则通过删除与修改后的内容匹配的 JSON 项目来修改对匹配请求的响应
JSONPath表达式。它们不会修改不是有效 JSON 文档的响应。
In AdGuard for Windows, Mac, and Android with CoreLibs v1.11 or later, $jsonprune
also supports modifying JSONP (padded JSON) documents.
在带有CoreLibs v1.11 或更高版本的 Windows、Mac 和 Android 版 AdGuard 中, $jsonprune
还支持修改 JSONP(填充 JSON)文档。
Syntax 句法
||example.org^$jsonprune=expression
removes items that match the modified JSONPath expressionexpression
from the response.
||example.org^$jsonprune=expression
从响应中删除与修改后的 JSONPathexpression
匹配的项目。
Due to the way rule parsing works, the characters $
and ,
must be escaped with \
inside expression
.
由于规则解析的工作方式,字符$
和,
必须在expression
内使用\
进行转义。
The modified JSONPath syntax has the following differences from the original:
修改后的 JSONPath 语法与原始语法有以下差异:
- Script expressions are not supported
不支持脚本表达式 - The supported filter expressions are:
支持的过滤器表达式有:?(has <key>)
— true if the current object has the specified key?(has <key>)
— 如果当前对象具有指定的键,则为 true?(key-eq <key> <value>)
— true if the current object has the specified key, and its value is equal to the specified value?(key-eq <key> <value>)
— 如果当前对象具有指定的键,并且其值等于指定的值,则为 true?(key-substr <key> <value>)
— true if the specified value is a substring of the value of the specified key of the current object?(key-substr <key> <value>)
— 如果指定值是当前对象的指定键值的子字符串,则为 true
- Whitespace outside of double- or single-quoted strings has no meaning
双引号或单引号字符串之外的空格没有意义 - Both double- and single-quoted strings can be used
双引号和单引号字符串都可以使用 - Expressions ending with
..
are not supported
不支持以..
结尾的表达式 - Multiple array slices can be specified in square brackets
可以在方括号中指定多个数组切片
There are various online tools that make working with JSONPath expressions more convenient:
有各种在线工具可以使使用 JSONPath 表达式更加方便:
https://www.site24x7.com/tools/jsonpath-finder-validator.html
https://jsonpathfinder.com/
https://jsonpath.com/
https://www.site24x7.com/tools/jsonpath-finder-validator.html https://jsonpathfinder.com/ https://jsonpath.com/
Keep in mind, though, that all JSONPath implementations have unique features/quirks and are subtly incompatible with each other.
但请记住,所有 JSONPath 实现都有独特的功能/怪癖,并且彼此之间存在微妙的不兼容。
Exceptions 例外情况
Basic URL exceptions shall not disable rules with the $jsonprune
modifier. They can be disabled as described below:
基本 URL 例外不得禁用带有$jsonprune
修饰符的规则。可以按如下所述禁用它们:
@@||example.org^$jsonprune
disables all$jsonprune
rules for responses from URLs matching||example.org^
.@@||example.org^$jsonprune
对来自匹配||example.org^
URL 的响应禁用所有$jsonprune
规则。@@||example.org^$jsonprune=text
disables all$jsonprune
rules with the value of the$jsonprune
modifier equal totext
for responses from URLs matching||example.org^
.
@@||example.org^$jsonprune=text
禁用所有$jsonprune
规则,其$jsonprune
修饰符的值等于来自匹配||example.org^
URL 的响应的text
。
$jsonprune
rules can also be disabled by $document
, $content
and $urlblock
exception rules.$jsonprune
规则也可以通过$document
、 $content
和$urlblock
异常规则禁用。
When multiple $jsonprune
rules match the same request, they are sorted in lexicographical order, the first rule is applied to the original response, and each of the remaining rules is applied to the result of applying the previous one.
当多个$jsonprune
规则匹配同一请求时,它们按字典顺序排序,第一个规则应用于原始响应,其余每个规则应用于应用前一个规则的结果。
Examples 示例
||example.org^$jsonprune=\$..[one\, "two three"]
removes all occurrences of the keys "one" and "two three" anywhere in the JSON document.
||example.org^$jsonprune=\$..[one\, "two three"]
删除 JSON 文档中任意位置出现的所有键“一”和“二三”。
Input 输入
Output 输出
||example.org^$jsonprune=\$.a[?(has ad_origin)]
removes all children ofa
that have anad_origin
key.
||example.org^$jsonprune=\$.a[?(has ad_origin)]
删除a
的所有具有ad_origin
键的子级。
Input 输入
Output 输出
||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')]
removes all items that are at nesting level 3 and have a property "Some key" equal to "Some value".
||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')]
删除嵌套级别 3 且属性“Some key”等于“Some value”的所有项目。
Input 输入
Output 输出
Nested JSONPath expressions
嵌套 JSONPath 表达式
In AdGuard for Windows, Mac and Android with CoreLibs v1.11 or later, JSONPath expressions may be used as keys in filter expressions.
在带有CoreLibs v1.11 或更高版本的 Windows、Mac 和 Android 版 AdGuard 中,JSONPath 表达式可以用作过滤器表达式中的键。
||example.org^$jsonprune=\$.elems[?(has "\$.a.b.c")]
removes all children ofelems
which have a property selectable by the JSONPath expression$.a.b.c
.
||example.org^$jsonprune=\$.elems[?(has "\$.a.b.c")]
删除具有可由 JSONPath 表达式$.abc
选择的属性的elems
的所有子级。
Input 输入
Output 输出
||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")]
removes all children ofelems
which have a property selectable by the JSONPath expression$.a.b.c
with a value equal to"abc"
.
||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")]
删除具有可由 JSONPath 表达式$.abc
选择且值等于"abc"
的属性的elems
的所有子级。
Input 输入
Output 输出
$jsonprune
rules are only compatible with these modifiers:$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and$xmlhttprequest
.$jsonprune
规则仅与以下修饰符兼容:$domain
、$third-party
、$strict-third-party
、$strict-first-party
、$app
、$important
、$match-case
和$xmlhttprequest
。$jsonprune
rules do not apply if the size of the original response is greater than 10 MB.
如果原始响应的大小大于 10 MB,则$jsonprune
规则不适用。
$xmlprune
$xmlprune
rules modify the response to a matching request by removing XML items that match an XPath 1.0 expression.
The expression must return a node-set.
$xmlprune
rules do not modify responses which are not well-formed XML documents.$xmlprune
规则通过删除与XPath 1.0表达式匹配的 XML 项来修改对匹配请求的响应。该表达式必须返回一个节点集。
$xmlprune
规则不会修改不是格式良好的 XML 文档的响应。
Syntax 句法
||example.org^$xmlprune=expression
removes items that match the XPath expressionexpression
from the response.
||example.org^$xmlprune=expression
从响应中删除与 XPathexpression
匹配的项目。
Due to the way rule parsing works, the characters $
and ,
must be escaped with \
inside expression
.
由于规则解析的工作方式,字符$
和,
必须在expression
内使用\
进行转义。
Exceptions 例外情况
Basic URL exceptions shall not disable rules with the $xmlprune
modifier. They can be disabled as described below:
基本 URL 例外不得禁用带有$xmlprune
修饰符的规则。可以按如下所述禁用它们:
@@||example.org^$xmlprune
disables all$xmlprune
rules for responses from URLs matching||example.org^
.@@||example.org^$xmlprune
对来自匹配||example.org^
URL 的响应禁用所有$xmlprune
规则。@@||example.org^$xmlprune=text
disables all$xmlprune
rules with the value of the$xmlprune
modifier equal totext
for responses from URLs matching||example.org^
.
@@||example.org^$xmlprune=text
禁用所有$xmlprune
规则,其中$xmlprune
修饰符的值等于来自匹配||example.org^
URL 的响应的text
。
$xmlprune
rules can also be disabled by $document
, $content
and $urlblock
exception rules.$xmlprune
规则也可以通过$document
、 $content
和$urlblock
异常规则禁用。
When multiple $xmlprune
rules match the same request, they are applied in lexicographical order.
当多个$xmlprune
规则匹配同一请求时,它们将按字典顺序应用。
Examples 示例
||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1]
removes odd-numbered books from the bookstore.
||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1]
从书店中删除奇数书籍。
Input 输入
Output 输出
||example.org^$xmlprune=/bookstore/book[year = 2003]
removes books from the year 2003 from the bookstore.
||example.org^$xmlprune=/bookstore/book[year = 2003]
从书店中删除 2003 年的书籍。
Input 输入
Output 输出
||example.org^$xmlprune=//*/@*
removes all attributes from all elements.
||example.org^$xmlprune=//*/@*
删除所有元素的所有属性。
Input 输入
Output 输出
$xmlprune
rules are only compatible with these modifiers:$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and$xmlhttprequest
.$xmlprune
规则仅与以下修饰符兼容:$domain
、$third-party
、$strict-third-party
、$strict-first-party
、$app
、$important
、$match-case
和$xmlhttprequest
。$xmlprune
rules do not apply if the size of the original response is greater than 10 MB.
如果原始响应的大小大于 10 MB,则$xmlprune
规则不适用。
$network
This is basically a Firewall-like rule allowing to fully block or unblock access to a specified remote address.
这基本上是一个类似防火墙的规则,允许完全阻止或取消阻止对指定远程地址的访问。
$network
rules match IP addresses only! You cannot use them to block or unblock access to a domain.$network
规则仅匹配IP地址!您不能使用它们来阻止或取消阻止对域的访问。- To match an IPv6 address, you have to use the collapsed syntax, e.g. use
[2001:4860:4860::8888]$network
instead of[2001:4860:4860:0:0:0:0:8888]$network
.
要匹配 IPv6 地址,您必须使用折叠语法,例如使用[2001:4860:4860::8888]$network
而不是[2001:4860:4860:0:0:0:0:8888]$network
。 - An allowlist
$network
rule makes AdGuard bypass data to the matching endpoint, hence there will be no further filtering at all.
白名单$network
规则使 AdGuard 绕过数据到匹配的端点,因此根本不会进行进一步的过滤。 - If the IP part starts and ends with
/
character, it is treated as a regular expression.
如果 IP 部分以/
字符开头和结尾,则将其视为正则表达式。
We recommend to get acquainted with this article for better understanding of regular expressions.
我们建议您熟悉本文,以便更好地理解正则表达式。
The $network
modifier can only be used in rules together with the $app
and $important
modifiers, and not with any other modifiers.$network
修饰符只能在规则中与$app
和$important
修饰符一起使用,而不能与任何其他修饰符一起使用。
Examples 示例
174.129.166.49:3478^$network
blocks access to174.129.166.49:3478
(but not to174.129.166.49:34788
).174.129.166.49:3478^$network
阻止访问174.129.166.49:3478
(但不阻止174.129.166.49:34788
)。[2001:4860:4860::8888]:443^$network
blocks access to[2001:4860:4860::8888]:443
.
[2001:4860:4860::8888]:443^$network
阻止访问[2001:4860:4860::8888]:443
。174.129.166.49$network
blocks access to174.129.166.49:*
.174.129.166.49$network
阻止访问174.129.166.49:*
。@@174.129.166.49$network
makes AdGuard bypass data to the endpoint. No other rules will be applied.@@174.129.166.49$network
使 AdGuard 绕过数据到端点。不适用其他规则。/.+:3[0-9]{4}/$network
blocks access to any port from 30000 to 39999./.+:3[0-9]{4}/$network
阻止访问 30000 到 39999 之间的任何端口。/8.8.8.(:?8|4)/$network
blocks access to both8.8.8.8
and8.8.8.4
./8.8.8.(:?8|4)/$network
阻止访问8.8.8.8
和8.8.8.4
。
Only AdGuard for Windows, Mac, and Android are technically capable of using rules with $network
modifier.
从技术上讲,只有适用于 Windows、Mac 和 Android 的 AdGuard 能够使用带有$network
修饰符的规则。
$permissions
This modifier completely changes the rule behavior. If it is applied to a rule, the rule will not block the matching request. Response headers will be modified instead.
此修饰符完全改变了规则行为。如果应用于规则,则该规则不会阻止匹配的请求。响应标头将被修改。
In order to use this type of rules, it is required to have a basic understanding of the Permissions Policy security layer.
为了使用此类规则,需要对权限策略安全层有基本的了解。
For the requests matching a $permissions
rule, AdGuard strengthens response's permissions policy by adding an additional permission policy equal to the $permissions
modifier contents. $permissions
rules are applied independently from any other rule type. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
对于匹配$permissions
规则的请求,AdGuard 通过添加与$permissions
修饰符内容相同的附加权限策略来增强响应的权限策略。 $permissions
规则的应用独立于任何其他规则类型。只有文档级异常可以影响它(请参阅示例部分),但没有其他基本规则。
Syntax 句法
$permissions
value syntax is identical to that of the Permissions-Policy
header syntax with the following exceptions:$permissions
值语法与Permissions-Policy
标头语法相同,但有以下例外:
- A comma that separates multiple features MUST be escaped — see examples below.
分隔多个功能的逗号必须转义 - 请参阅下面的示例。 - A pipe character (
|
) can be used instead of a comma to separate features.
可以使用竖线字符 (|
) 代替逗号来分隔功能。
The list of available directives is available here.
可用指令的列表可在此处找到。
$permissions
value can be empty in the case of exception rules — see examples below.
在例外规则的情况下, $permissions
值可以为空 - 请参阅下面的示例。
Examples 示例
||example.org^$permissions=autoplay=()
disallows autoplay media requested through theHTMLMediaElement
interface acrossexample.org
.
||example.org^$permissions=autoplay=()
不允许通过example.org
上的HTMLMediaElement
接口请求自动播放媒体。@@||example.org/page/*$permissions=autoplay=()
disables all rules with the$permissions
modifier exactly matchingautoplay=()
on all the pages matching the rule pattern. For instance, the rule above. It is important to note that the exception rule only takes effect in the case of an exact value match. For example, if you want to disable the rule$permissions=a=()\,b=()
, you need exception rule@@$permissions=a=()\,b=()
, and not@@$permissions=b=()\,a=()
, nor@@$permissions=b=()
becauseb=()\,a=()
orb=()
does not match witha=()\,b=()
.
@@||example.org/page/*$permissions=autoplay=()
在与规则模式匹配的所有页面上禁用与$permissions
修饰符完全匹配autoplay=()
所有规则。例如上面的规则。需要注意的是,例外规则仅在值精确匹配的情况下才生效。例如,如果要禁用规则$permissions=a=()\,b=()
,则需要例外规则@@$permissions=a=()\,b=()
,而不是@@$permissions=b=()\,a=()
,也不是@@$permissions=b=()
因为b=()\,a=()
或b=()
与a=()\,b=()
不匹配a=()\,b=()
。@@||example.org/page/*$permissions
disables all the$permissions
rules on all the pages matching the rule pattern.
@@||example.org/page/*$permissions
禁用与规则模式匹配的所有页面上的所有$permissions
规则。$domain=example.org|example.com,permissions=storage-access=()\, camera=()
disallows using the Storage Access API to request access to unpartitioned cookies and using video input devices acrossexample.org
andexample.com
.
$domain=example.org|example.com,permissions=storage-access=()\, camera=()
不允许使用存储访问 API 请求访问未分区的 cookie 以及跨example.org
和example.com
使用视频输入设备。$domain=example.org|example.com,permissions=storage-access=()|camera=()
does the same — a|
can be used to separate the features instead of an escaped comma.
$domain=example.org|example.com,permissions=storage-access=()|camera=()
做同样的事 - a|
可以用来分隔功能而不是转义逗号。@@||example.org^$document
or@@||example.org^$urlblock
disables all the$permission
rules on all the pages matching the rule pattern.@@||example.org^$document
或@@||example.org^$urlblock
禁用所有与规则模式匹配的页面上的所有$permission
规则。
$permissions
rules only take effect for main frame and sub frame requests. This means they are applied when a page is loaded or when an iframe is loaded.$permissions
规则仅对主框架和子框架请求生效。这意味着它们在加载页面或加载 iframe 时应用。
If there are multiple $permissions
rules that match the same request, multiple Permissions-Policy
headers will be added to the response for each rule with their $permissions
value. So if you have two rules: ||example.org^$permissions=autoplay=()
and ||example.org^$permissions=geolocation=()\,camera=()
that match the same request, the response will contain two Permissions-Policy
headers: autoplay=()
and geolocation=()\,camera=()
.
如果有多个$permissions
规则匹配同一请求,则多个Permissions-Policy
标头将添加到每个规则的响应中及其$permissions
值。所以如果你有两条规则: ||example.org^$permissions=autoplay=()
和 ||example.org^$permissions=geolocation=()\,camera=()
匹配相同的请求,响应将包含两个Permissions-Policy
标头: autoplay=()
和geolocation=()\,camera=()
。
$permissions
modifier limitations
$permissions
修饰符限制
Firefox ignores the Permissions-Policy
header. For more information, see this issue.
Firefox 会忽略Permissions-Policy
标头。有关更多信息,请参阅此问题。
- Characters forbidden in the
$permissions
value:$
.$permissions
值中禁止使用的字符:$
。 $permissions
is compatible with a limited set of modifiers:$domain
,$important
,$subdocument
, and content-type modifiers.$permissions
与一组有限的修饰符兼容:$domain
、$important
、$subdocument
和content-type modifiers 。$permissions
rules that do not have any content-type modifiers will match only requests where content type isdocument
.
没有任何内容类型修饰符的$permissions
规则将仅匹配内容类型为document
请求。
- Rules with the
$permissions
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
使用CoreLibs v1.11 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及带有TSUrlFilter v3.0.0 或更高版本的 AdGuard 浏览器扩展支持带有$permissions
修饰符的规则。 - Pipe separator
|
instead of escaped comma is supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.14 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
管道分离器|
带有CoreLibs v1.14 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及带有TSUrlFilter v3.0.0 或更高版本的 AdGuard 浏览器扩展支持代替转义逗号。
$redirect
AdGuard is able to redirect web requests to a local "resource".
AdGuard 能够将网络请求重定向到本地“资源”。
Syntax 句法
AdGuard uses the same filtering rule syntax as uBlock Origin. Also, it is compatible with ABP $rewrite=abp-resource
modifier.
AdGuard 使用与 uBlock Origin 相同的过滤规则语法。此外,它与 ABP $rewrite=abp-resource
修饰符兼容。
$redirect
is a modifier for the basic filtering rules so rules with this modifier support all other basic modifiers like $domain
, $third-party
, $script
, etc.$redirect
是基本过滤规则的修饰符,因此具有此修饰符的规则支持所有其他基本修饰符,例如$domain
、 $third-party
、 $script
等。
The value of the $redirect
modifier must be the name of the resource that will be used for redirection.$redirect
修饰符的值必须是将用于重定向的资源的名称。
Disabling $redirect
rules
禁用$redirect
规则
||example.org/script.js$script,redirect=noopjs
— this rule redirects all requests toexample.org/script.js
to the resource namednoopjs
.
||example.org/script.js$script,redirect=noopjs
— 此规则将所有对example.org/script.js
请求重定向到名为noopjs
的资源。||example.org/test.mp4$media,redirect=noopmp4-1s
— this rule redirects all requests toexample.org/test.mp4
to the resource namednoopmp4-1s
.
||example.org/test.mp4$media,redirect=noopmp4-1s
— 此规则将所有对example.org/test.mp4
的请求重定向到名为noopmp4-1s
的资源。@@||example.org^$redirect
will disable all$redirect
rules for URLs that match||example.org^
.@@||example.org^$redirect
将禁用与||example.org^
匹配的 URL 的所有$redirect
规则。@@||example.org^$redirect=nooptext
will disable all rules with$redirect=nooptext
for any request that matches||example.org^
.
@@||example.org^$redirect=nooptext
对于任何匹配||example.org^
的请求,将禁用$redirect=nooptext
的所有规则。
More information on redirects and their usage is available on GitHub.
有关重定向及其用法的更多信息,请访问GitHub 。
Priorities of $redirect
rules
$redirect
规则的优先级
$redirect
rules have higher priority than regular basic blocking rules.
This means that if there is a basic blocking rule, the $redirect
rule will override it.
Allowlist rules with @@
mark have higher priority than $redirect
rules.
If a basic rule with the $important
modifier and the $redirect
rule matches the same URL,
the latter is overridden unless it's also marked as $important
.$redirect
规则比常规基本阻止规则具有更高的优先级。这意味着如果存在基本阻止规则, $redirect
规则将覆盖它。带有@@
标记的白名单规则比$redirect
规则具有更高的优先级。如果带有$important
修饰符的基本规则和$redirect
规则匹配相同的 URL,则后者将被覆盖,除非它也被标记为$important
。
In short: $important
> @@
> $redirect
> basic rules
.
简而言之: $important
> @@
> $redirect
> basic rules
。
Go to rules priorities for more details.
请参阅规则优先级了解更多详细信息。
$redirect
modifier limitations
$redirect
修饰符限制
In AdGuard for Chrome MV3 allowlist rules with $redirect
are not supported.
在AdGuard for Chrome MV3中,不支持使用$redirect
的白名单规则。
- Rules with
$redirect
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari .
AdGuard 内容拦截器、 AdGuard for iOS和AdGuard for Safari不支持带有$redirect
修饰符的规则。 $redirect
in uBlock Origin supports specifying priority, e.g.$redirect=noopjs:42
. AdGuard does not support it and instead just discards the priority postfix.
uBlock Origin 中的$redirect
支持指定优先级,例如$redirect=noopjs:42
。 AdGuard 不支持它,而是丢弃优先级后缀。
$redirect-rule
This is basically an alias to $redirect
since it has the same "redirection" values and the logic is almost similar. The difference is that $redirect-rule
is applied only in the case when the target request is blocked by a different basic rule.
这基本上是$redirect
的别名,因为它具有相同的“重定向”值并且逻辑几乎相似。不同之处在于$redirect-rule
仅在目标请求被不同的基本规则阻止的情况下应用。
Go to rules priorities for more details.
请参阅规则优先级了解更多详细信息。
Negating $redirect-rule
works exactly the same way as for regular $redirect
rules. Even more than that, @@||example.org^$redirect
will negate both $redirect
and $redirect-rule
rules.
否定$redirect-rule
工作方式与常规$redirect
规则完全相同。更重要的是, @@||example.org^$redirect
将否定$redirect
和$redirect-rule
规则。
Examples 示例
||example.org/script.js
||example.org^$redirect-rule=noopjs
In this case, only requests to example.org/script.js
will be "redirected" to noopjs
. All other requests to example.org
will be kept intact.
在这种情况下,只有对example.org/script.js
的请求才会被“重定向”到noopjs
。对example.org
所有其他请求将保持不变。
Rules with $redirect-rule
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, AdGuard for Safari, and AdGuard for Chrome MV3. The discussion about adding support for $redirect-rule
rules in Chrome MV3 extensions is currently open.
AdGuard Content Blocker 、 AdGuard for iOS 、 AdGuard for Safari和AdGuard for Chrome MV3不支持带有$redirect-rule
修饰符的规则。关于在 Chrome MV3 扩展中添加对$redirect-rule
规则的支持的讨论目前正在进行中。
$referrerpolicy
These rules allow overriding of a page's referrer policy.
Responses to matching requests will have all of their Referrer-Policy
headers replaced with a single header with the value equal to the matching rule's modifier value.
If the response carries an HTML document with a <meta name="referrer"...
tag, the content
attribute of the tag will also be replaced with the modifier value.
这些规则允许覆盖页面的引荐来源网址策略。对匹配请求的响应将其所有Referrer-Policy
标头替换为单个标头,其值等于匹配规则的修饰符值。如果响应携带带有<meta name="referrer"...
标记的 HTML 文档,则该标记的content
属性也将替换为修饰符值。
An exception rule with a modifier value disables the blocking rule with the same modifier value.
An exception rule without a modifier value disables all matched referrer-policy rules.
具有修饰符值的例外规则会禁用具有相同修饰符值的阻止规则。没有修饰符值的例外规则会禁用所有匹配的引荐来源网址策略规则。
If a request matches multiple $referrerpolicy
rules not disabled by exceptions, only one of them (it is not specified which one) is applied. $referrerpolicy
rules without specified content-type modifiers apply to $document
and $subdocument
content types.
如果请求匹配多个未因异常而禁用的$referrerpolicy
规则,则仅应用其中之一(未指定哪一个)。没有指定内容类型修饰符的$referrerpolicy
规则适用于$document
和$subdocument
内容类型。
Examples 示例
||example.com^$referrerpolicy=unsafe-url
overrides the referrer policy forexample.com
withunsafe-url
.
||example.com^$referrerpolicy=unsafe-url
使用unsafe-url
覆盖example.com
的引荐来源网址策略。@@||example.com^$referrerpolicy=unsafe-url
disables the previous rule.
@@||example.com^$referrerpolicy=unsafe-url
禁用之前的规则。@@||example.com/abcd.html^$referrerpolicy
disables all$referrerpolicy
rules onexample.com/abcd.html
.
@@||example.com/abcd.html^$referrerpolicy
禁用example.com/abcd.html
上的所有$referrerpolicy
规则。
$removeheader
Rules with $removeheader
modifier are intended to remove headers from HTTP requests and responses. The initial motivation for this rule type is to be able to get rid of the Refresh
header which is often used to redirect users to an undesirable location. However, this is not the only case where this modifier can be useful.
带有$removeheader
修饰符的规则旨在从 HTTP 请求和响应中删除标头。此规则类型的最初动机是能够摆脱Refresh
标头,该标头通常用于将用户重定向到不需要的位置。然而,这并不是该修饰符有用的唯一情况。
Just like $csp
, $redirect
, $removeparam
, and $cookie
, this modifier exists independently, rules with it do not depend on the regular basic rules, i.e. regular exception or blocking rules will not affect it. By default, it only affects response headers. However, you can also change it to remove headers from HTTP requests as well.
就像$csp
、 $redirect
、 $removeparam
和$cookie
一样,这个修饰符独立存在,带有它的规则不依赖于常规的基本规则,即常规的异常或阻塞规则不会影响它。默认情况下,它仅影响响应标头。但是,您也可以更改它以从 HTTP 请求中删除标头。
Syntax 句法
Basic syntax 基本语法
||example.org^$removeheader=header-name
removes a response header calledheader-name
||example.org^$removeheader=header-name
删除名为header-name
的响应标头||example.org^$removeheader=request:header-name
removes a request header calledheader-name
||example.org^$removeheader=request:header-name
删除名为header-name
的请求标头
$removeheader
is case-insensitive, but we suggest always using lower case.$removeheader
不区分大小写,但我们建议始终使用小写。
Negating $removeheader
否定$removeheader
This type of rules works pretty much the same way it works with $csp
and $redirect
modifiers.
这种类型的规则的工作方式与$csp
和$redirect
修饰符的工作方式几乎相同。
Use @@
to negate $removeheader
:
使用@@
来否定$removeheader
:
@@||example.org^$removeheader
negates all$removeheader
rules for URLs that match||example.org^
.@@||example.org^$removeheader
否定与||example.org^
匹配的 URL 的所有$removeheader
规则。@@||example.org^$removeheader=header
negates the rule with$removeheader=header
for any request matching||example.org^
.
@@||example.org^$removeheader=header
对于任何匹配||example.org^
请求,使用$removeheader=header
否定规则。
$removeheader
rules can also be disabled by $document
and $urlblock
exception rules. But basic exception rules without modifiers will not do that. For example, @@||example.com^
will not disable $removeheader=p
for requests to example.com
, but @@||example.com^$urlblock
will.$removeheader
规则也可以通过$document
和$urlblock
异常规则禁用。但没有修饰符的基本例外规则不会这样做。例如, @@||example.com^
不会禁用$removeheader=p
对于example.com
的请求,但@@||example.com^$urlblock
会。
In case of multiple $removeheader
rules matching a single request, we will apply each of them one by one.
如果多个$removeheader
规则匹配单个请求,我们将一一应用它们。
Examples 示例
||example.org^$removeheader=refresh
removesRefresh
header from all HTTP responses returned byexample.org
and its subdomains.
||example.org^$removeheader=refresh
从example.org
及其子域返回的所有 HTTP 响应中删除Refresh
标头。||example.org^$removeheader=request:x-client-data
removesX-Client-Data
header from all HTTP requests.
||example.org^$removeheader=request:x-client-data
从所有 HTTP 请求中删除X-Client-Data
标头。Next block of rules removes
Refresh
andLocation
headers from all HTTP responses returned byexample.org
save for requests toexample.org/path/*
, for which no headers will be removed:
下一个规则块将从example.org
返回的所有 HTTP 响应中删除Refresh
和Location
标头,保存对example.org/path/*
的请求,不会删除任何标头:||example.org^$removeheader=refresh
||example.org^$removeheader=location
@@||example.org/path/$removeheader
This type of rules can only be used in trusted filters.
这种类型的规则只能在受信任的过滤器中使用。
In order to avoid compromising the security
$removeheader
cannot remove headers from the list below:
为了避免损害安全性,$removeheader
无法从下面的列表中删除标头:access-control-allow-origin
access-control-allow-credentials
access-control-allow-headers
access-control-allow-methods
access-control-expose-headers
access-control-max-age
access-control-request-headers
access-control-request-method
origin
timing-allow-origin
allow
cross-origin-embedder-policy
cross-origin-opener-policy
cross-origin-resource-policy
content-security-policy
content-security-policy-report-only
expect-ct
feature-policy
origin-isolation
strict-transport-security
upgrade-insecure-requests
x-content-type-options
x-download-options
x-frame-options
x-permitted-cross-domain-policies
x-powered-by
x-xss-protection
public-key-pins
public-key-pins-report-only
sec-websocket-key
sec-websocket-extensions
sec-websocket-accept
sec-websocket-protocol
sec-websocket-version
p3p
sec-fetch-mode
sec-fetch-dest
sec-fetch-site
sec-fetch-user
referrer-policy
content-type
content-length
accept
accept-encoding
host
connection
transfer-encoding
upgrade
$removeheader
rules are only compatible with$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and content type modifiers such as$script
and$stylesheet
. The rules which have any other modifiers are considered invalid and will be discarded.$removeheader
规则仅与$domain
、$third-party
、$strict-third-party
、$strict-first-party
、$app
、$important
、$match-case
以及内容类型修饰符(例如$script
和$stylesheet
兼容$stylesheet
。具有任何其他修饰符的规则将被视为无效并被丢弃。
Rules with $removeheader
modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Chrome, Firefox, and Edge.
带$removeheader
修饰符的规则受适用于 Windows 的 AdGuard、适用于 Mac 的 AdGuard、适用于 Android 的 AdGuard 以及适用于 Chrome、Firefox 和 Edge 的 AdGuard 浏览器扩展支持。
$removeparam
$queryprune
is an alias of $removeparam
. Since $queryprune
is deprecated, avoid using it and use $removeparam
instead.$queryprune
是$removeparam
的别名。由于$queryprune
已被弃用,因此请避免使用它并使用$removeparam
代替。
Rules with $removeparam
modifier are intended to strip query parameters from requests' URLs. Please note that such rules are only applied to GET
, HEAD
, OPTIONS
, and sometimes POST
requests.
带有$removeparam
修饰符的规则旨在从请求的 URL 中删除查询参数。请注意,此类规则仅适用于GET
、 HEAD
、 OPTIONS
,有时还适用于POST
请求。
Syntax 句法
Basic syntax 基本语法
$removeparam=param
removes query parameter with the nameparam
from URLs of any request, e.g. a request tohttp://example.com/page?param=1&another=2
will be transformed intohttp://example.com/page?another=2
.$removeparam=param
从任何请求的 URL 中删除带有名称param
查询参数,例如请求http://example.com/page?param=1&another=2
将转化为http://example.com/page?another=2
。
Regular expressions 正则表达式
You can also use regular expressions to match query parameters and/or their values:
您还可以使用正则表达式来匹配查询参数和/或其值:
$removeparam=/regexp/[options]
— removes query parameters that matches theregexp
regular expression from URLs of any request. Unlike basic syntax, it means "remove query parameters normalized to aname=value
string which match theregexp
regular expression".[options]
here is the list of regular expression options. At the moment, the only supported option isi
which makes matching case-insensitive.
$removeparam=/regexp/[options]
— 从任何请求的 URL 中删除与regexp
正则表达式匹配的查询参数。与基本语法不同,它的意思是“删除规范化为与regexp
正则表达式匹配的name=value
字符串的查询参数” 。[options]
这里是正则表达式选项的列表。目前,唯一支持的选项是i
,它使匹配不区分大小写。
Escaping special characters
转义特殊字符
Do not forget to escape special characters like ,
, /
and $
in the regular expressions. Use \
character for that purpose. For example, an escaped comma should look like this: \,
.
不要忘记在正则表达式中转义,
、 /
和$
等特殊字符。为此目的使用\
字符。例如,转义逗号应如下所示: \,
。
Regexp-type rules target both name and value of the parameter. To minimize mistakes, it is safer to start every regexp with /^
unless you specifically target parameter values.
正则表达式类型规则以参数的名称和值为目标。为了最大限度地减少错误,除非您专门针对参数值,否则以/^
开头每个正则表达式会更安全。
We will try to detect and ignore unescaped $
automatically using a simple rule of thumb — it is not an options delimiter if all three are true:
我们将尝试使用简单的经验法则自动检测和忽略未转义的$
— 如果这三个都为 true,则它不是选项分隔符:
- It looks like
$/
看起来像$/
- There is another slash character
/
to the left of it
其左侧还有一个斜杠字符/
- There is another unescaped dollar sign
$
to the left of that slash character
该斜杠字符的左侧还有另一个未转义的美元符号$
Remove all query parameters
删除所有查询参数
Specify naked $removeparam
to remove all query parameters:
指定naked $removeparam
以删除所有查询参数:
||example.org^$removeparam
— removes all query parameters from URLs matching||example.org^
.||example.org^$removeparam
— 从匹配||example.org^
URL 中删除所有查询参数。
Inversion 反转
Use ~
to apply inversion:
使用~
应用反转:
$removeparam=~param
— removes all query parameters with the name different fromparam
.$removeparam=~param
— 删除名称与param
不同的所有查询参数。$removeparam=~/regexp/
— removes all query parameters that do not match theregexp
regular expression.$removeparam=~/regexp/
— 删除所有与regexp
正则表达式不匹配的查询参数。
Negating $removeparam
否定$removeparam
This sort of rules work pretty much the same way it works with $csp
and $redirect
modifiers.
这种规则的工作方式与$csp
和$redirect
修饰符的工作方式几乎相同。
Use @@
to negate $removeparam
:
使用@@
来否定$removeparam
:
@@||example.org^$removeparam
negates all$removeparam
rules for URLs that match||example.org^
.@@||example.org^$removeparam
否定匹配||example.org^
URL 的所有$removeparam
规则。@@||example.org^$removeparam=param
negates the rule with$removeparam=param
for any request matching||example.org^
.
@@||example.org^$removeparam=param
对于任何匹配||example.org^
请求,使用$removeparam=param
否定规则。@@||example.org^$removeparam=/regexp/
negates the rule with$removeparam=/regexp/
for any request matching||example.org^
.
@@||example.org^$removeparam=/regexp/
对于任何匹配||example.org^
请求,使用$removeparam=/regexp/
否定规则。
Multiple rules matching a single request
多个规则匹配单个请求
In the case when multiple $removeparam
rules match a single request, each of them will be applied one by one.
如果多个$removeparam
规则与单个请求匹配,则每个规则都将被一一应用。
Examples 示例
$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam
With these rules some UTM parameters will be stripped out from any request, except that requests to example.com
will not be stripped at all, e.g. http://google.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
will be transformed to http://google.com/page
, but http://example.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
will not be affected by the blocking rule.
使用这些规则,某些UTM 参数将从任何请求中删除,但对example.com
的请求根本不会被删除,例如 http://google.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
将转换为http://google.com/page
,但是 http://example.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
不会受到屏蔽规则的影响。
$removeparam=utm_source
removesutm_source
query parameter from all requests.$removeparam=utm_source
从所有请求中删除utm_source
查询参数。$removeparam=/utm_.*/
removes allutm_* query
parameters from URL queries of any request, e.g. a request tohttp://example.com/page?utm_source=test
will be transformed tohttp://example.com/page
.$removeparam=/utm_.*/
从任何请求的 URL 查询中删除所有utm_* query
参数,例如请求http://example.com/page?utm_source=test
将转换为http://example.com/page
。$removeparam=/^utm_source=campaign$/
removesutm_source
query parameter with the value equal tocampaign
. It does not touch otherutm_source
parameters.
$removeparam=/^utm_source=campaign$/
删除utm_source
查询参数,其值等于campaign
。它不会触及其他utm_source
参数。
Negating one $removeparam
rule and replacing it with a different rule
否定一条$removeparam
规则并将其替换为另一条规则
$removeparam=/^(gclid|yclid|fbclid)=/
@@||example.com^$removeparam=/^(gclid|yclid|fbclid)=/
||example.com^$removeparam=/^(yclid|fbclid)=/
With these rules, Google, Yandex, and Facebook Click IDs will be removed from all requests. There is one exception: Google Click ID (gclid) will not be removed from requests to example.com.
根据这些规则,Google、Yandex 和 Facebook 点击 ID 将从所有请求中删除。有一个例外:Google 点击 ID (gclid) 不会从对 example.com 的请求中删除。
Negating $removeparam
for all parameters
对所有参数否定$removeparam
$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam
With these rules, specified UTM parameters will be removed from any request save for requests to example.org
.
使用这些规则,指定的 UTM 参数将从保存到example.org
的请求中删除。
$removeparam
rules can also be disabled by $document
and $urlblock
exception rules. But basic exception rules without modifiers do not do that. For example, @@||example.com^
will not disable $removeparam=p
for requests to example.com, but @@||example.com^$urlblock
will.$removeparam
规则也可以通过$document
和$urlblock
异常规则禁用。但不带修饰符的基本异常规则则不能做到这一点。例如, @@||example.com^
不会禁用$removeparam=p
对于example.com的请求,但@@||example.com^$urlblock
会。
$removeparam
modifier limitations
$removeparam
修饰符限制
AdGuard for Chrome MV3 has some limitations:
AdGuard for Chrome MV3有一些限制:
Regular expressions, negation and allowlist rules are not supported.
不支持正则表达式、否定和白名单规则。Group of similar
$removeparam
rules will be combined into one. Example:
一组类似的$removeparam
规则将合并为一个。例子:||testcases.adguard.com$xmlhttprequest,removeparam=p1case1
||testcases.adguard.com$xmlhttprequest,removeparam=p2case1
||testcases.adguard.com$xmlhttprequest,removeparam=P3Case1
$xmlhttprequest,removeparam=p1case2is converted to 被转换为
[
{
"id": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": {
"queryTransform": {
"removeParams": [
"p1case1",
"p2case1",
"P3Case1"
]
}
}
}
},
"condition": {
"urlFilter": "||testcases.adguard.com",
"resourceTypes": [
"xmlhttprequest"
],
"isUrlFilterCaseSensitive": false
}
},
{
"id": 4,
"action": {
"type": "redirect",
"redirect": {
"transform": {
"queryTransform": {
"removeParams": [
"p1case2"
]
}
}
}
},
"condition": {
"resourceTypes": [
"xmlhttprequest"
],
"isUrlFilterCaseSensitive": false
}
}
]
- Rules with the
$removeparam
modifier can only be used in trusted filters.
带有$removeparam
修饰符的规则只能在受信任的过滤器中使用。 $removeparam
rules are compatible with basic modifiers, content-type modifiers, and with the$important
and$app
modifiers. Rules with any other modifiers are considered invalid and will be discarded.$removeparam
规则与基本修饰符、内容类型修饰符以及$important
和$app
修饰符兼容。具有任何其他修饰符的规则将被视为无效并将被丢弃。$removeparam
rules without content type modifiers will only match requests where the content type isdocument
.
不带内容类型修饰符的$removeparam
规则将仅匹配内容类型为document
请求。
- Rules with
$removeparam
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.7 or later, and AdGuard Browser Extension v3.6 or later.
带$removeparam
修饰符的规则受包含CoreLibs v1.7 或更高版本以及 AdGuard 浏览器扩展 v3.6 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持。 $removeparam
syntax for regular expressions is supported AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.8 or later, and AdGuard Browser Extension v4.0 or later.
正则表达式的$removeparam
语法受CoreLibs v1.8 或更高版本以及 AdGuard 浏览器扩展 v4.0 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持。POST
request types are supported only by AdGuard for Windows, Mac, and Android with CoreLibs v1.10 or later, and AdGuard Browser Extension with TSWebExtension v0.4.6 or later.POST
请求类型仅受具有CoreLibs v1.10 或更高版本的 Windows、Mac 和 Android 版 AdGuard 以及具有TSWebExtension v0.4.6 或更高版本的 AdGuard 浏览器扩展支持。
$replace
This modifier completely changes the rule behavior. If it is applied, the rule will not block the request. The response is going to be modified instead.
此修饰符完全改变了规则行为。如果应用,该规则将不会阻止该请求。相反,响应将被修改。
You will need some knowledge of regular expressions to use $replace
modifier.
您需要一些正则表达式知识才能使用$replace
修饰符。
Features 特征
$replace
rules apply to any text response, but will not apply to binary (media
,image
,object
, etc.).$replace
规则适用于任何文本响应,但不适用于二进制(media
、image
、object
等)。$replace
rules do not apply if the size of the original response is more than 10 MB.
如果原始响应的大小超过 10 MB,则$replace
规则不适用。$replace
rules have a higher priority than other basic rules (including exception rules). So if a request natches two different rules, one of which has the$replace
modifier, this rule will be applied.$replace
规则比其他基本规则(包括例外规则)具有更高的优先级。因此,如果一个请求捕获两个不同的规则,其中之一具有$replace
修饰符,则将应用该规则。- Document-level exception rules with
$content
or$document
modifiers do disable$replace
rules for requests matching them.
带有$content
或$document
修饰符的文档级异常规则会禁用匹配它们的请求的$replace
规则。 - Other document-level exception rules (
$generichide
,$elemhide
or$jsinject
modifiers) are applied alongside$replace
rules. It means that you can modify the page content with a$replace
rule and disable cosmetic rules there at the same time.
其他文档级异常规则($generichide
、$elemhide
或$jsinject
修饰符)与$replace
规则一起应用。这意味着您可以使用$replace
规则修改页面内容并同时禁用修饰规则。
$replace
value can be empty in the case of exception rules. See examples section for further information.
如果有例外规则, $replace
值可以为空。有关更多信息,请参阅示例部分。
Multiple rules matching a single request
多个规则匹配单个请求
In case if multiple $replace
rules match a single request, we will apply each of them. The order is defined alphabetically.
如果多个$replace
规则与单个请求匹配,我们将应用每个规则。顺序是按字母顺序定义的。
Syntax 句法
In general, $replace
syntax is similar to replacement with regular expressions in Perl.
一般来说, $replace
语法类似于Perl 中的正则表达式替换。
replace = "/" regexp "/" replacement "/" modifiers
regexp
— a regular expression.regexp
— 正则表达式。replacement
— a string that will be used to replace the string corresponding toregexp
.replacement
— 将用于替换与regexp
对应的字符串的字符串。modifiers
— a regular expression flags. For example,i
— insensitive search, ors
— single-line mode.modifiers
——正则表达式标志。例如,i
— 不敏感搜索,或s
— 单行模式。
In the $replace
value, two characters must be escaped: comma ,
and dollar sign $
. Use backslash \
for it. For example, an escaped comma looks like this: \,
.
在$replace
值中,必须转义两个字符:逗号,
美元符号$
。使用反斜杠\
来表示它。例如,转义逗号如下所示: \,
。
Examples 示例
||example.org^$replace=/(<VAST[\s\S]*?>)[\s\S]*<\/VAST>/\$1<\/VAST>/i
There are three parts in this rule:
该规则分为三个部分:
regexp
—(<VAST(.|\s)*?>)(.|\s)*<\/VAST>
;regexp
—(<VAST(.|\s)*?>)(.|\s)*<\/VAST>
;replacement
—\$1<\/VAST>
where$
is escaped;replacement
-\$1<\/VAST>
其中$
被转义;modifiers
—i
for insensitive search.modifiers
-i
表示不敏感搜索。
You can see how this rule works here:
http://regexr.com/3cesk
您可以在此处查看此规则的运作方式:
http://regexr.com/3cesk
Multiple $replace
rules
多个$replace
规则
||example.org^$replace=/X/Y/
||example.org^$replace=/Z/Y/
@@||example.org/page/*$replace=/Z/Y/
- Both rule 1 and 2 will be applied to all requests sent to
example.org
.
规则 1 和 2 都将应用于发送到example.org
所有请求。 - Rule 2 is disabled for requests matching
||example.org/page/
, but rule 1 still works!
对于匹配||example.org/page/
请求,规则 2 被禁用,但规则 1 仍然有效!
Disabling $replace
rules
禁用$replace
规则
@@||example.org^$replace
will disable all$replace
rules matching||example.org^
.@@||example.org^$replace
将禁用所有匹配||example.org^
$replace
规则。@@||example.org^$document
or@@||example.org^$content
will disable all$replace
rules originated from pages ofexample.org
including the page itself.@@||example.org^$document
或@@||example.org^$content
将禁用源自example.org
页面(包括页面本身)的所有$replace
规则。
Rules with the $replace
modifier can only be used in trusted filters.
带有$replace
修饰符的规则只能在受信任的过滤器中使用。
Rules with $replace
modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Firefox. Such rules do not work in extensions for other browsers because they are unable to modify content on the network level.
带$replace
修饰符的规则受 AdGuard for Windows、AdGuard for Mac、AdGuard for Android 和 AdGuard Browser Extension for Firefox 支持。此类规则不适用于其他浏览器的扩展,因为它们无法修改网络级别的内容。
$urltransform
The $urltransform
rules allow you to modify the request URL by replacing text matched by a regular expression.$urltransform
规则允许您通过替换与正则表达式匹配的文本来修改请求 URL。
Features 特征
$urltransform
rules normally only apply to the path and query parts of the URL, see below for one exception.$urltransform
规则通常仅适用于 URL 的路径和查询部分,请参阅下面的一个例外。$urltransform
will not be applied if the original URL is blocked by other rules.
如果原始 URL 被其他规则阻止,则不会应用$urltransform
。$urltransform
will be applied before$removeparam
rules.$urltransform
将在$removeparam
规则之前应用。
The $urltransform
value can be empty for exception rules.
对于例外规则, $urltransform
值可以为空。
Multiple rules matching a single request
多个规则匹配单个请求
If multiple $urltransform
rules match a single request, we will apply each of them. The order is defined alphabetically.
如果多个$urltransform
规则与单个请求匹配,我们将应用每个规则。顺序是按字母顺序定义的。
Syntax 句法
$urltransform
syntax is similar to replacement with regular expressions in Perl.$urltransform
语法类似于Perl 中的正则表达式替换。
urltransform = "/" regexp "/" replacement "/" modifiers
regexp
— a regular expression.regexp
— 正则表达式。replacement
— a string that will be used to replace the string corresponding toregexp
.replacement
— 将用于替换与regexp
对应的字符串的字符串。modifiers
— a regular expression flags. For example,i
— insensitive search, ors
— single-line mode.modifiers
——正则表达式标志。例如,i
— 不敏感搜索,或s
— 单行模式。
In the $urltransform
value, two characters must be escaped: the comma ,
and the dollar sign $
. Use the backslash character \
for this. For example, an escaped comma looks like this: \,
.
在$urltransform
值中,必须转义两个字符:逗号,
美元符号$
。为此,请使用反斜杠字符\
。例如,转义逗号如下所示: \,
。
Changing the origin 改变原点
As stated above, normally $urltransform
rules are only allowed to change the path and query parts of the URL.
However, if the rule's regexp
begins with the string ^http
, then the full URL is searched and can be modified by the rule.
Such a rule will not be applied if the URL transformation can not be achieved via an HTTP redirect (for example, if the request's method is POST
).
如上所述,通常$urltransform
规则只允许更改 URL 的路径和查询部分。但是,如果规则的regexp
以字符串^http
开头,则将搜索完整的 URL,并且规则可以对其进行修改。如果无法通过 HTTP 重定向实现 URL 转换(例如,如果请求的方法是POST
),则不会应用此类规则。
Examples 示例
||example.org^$urltransform=/(pref\/).*\/(suf)/\$1\$2/i
There are three parts in this rule:
该规则分为三个部分:
regexp
—(pref\/).*\/(suf)
;regexp
—(pref\/).*\/(suf)
;replacement
—\$1\$2
where$
is escaped;replacement
—\$1\$2
其中$
被转义;modifiers
—i
for insensitive search.modifiers
-i
表示不敏感搜索。
Multiple $urltransform
rules
多个$urltransform
规则
||example.org^$urltransform=/X/Y/
||example.org^$urltransform=/Z/Y/
@@||example.org/page/*$urltransform=/Z/Y/
- Both rule 1 and 2 will be applied to all requests sent to
example.org
.
规则 1 和 2 都将应用于发送到example.org
所有请求。 - Rule 2 is disabled for requests matching
||example.org/page/
, but rule 1 still works!
对于匹配||example.org/page/
请求,规则 2 被禁用,但规则 1 仍然有效!
Re-matching rules after transforming the URL
URL转换后重新匹配规则
After applying all matching $urltransform
rules, the transformed request will be matched against all other rules:
应用所有匹配的$urltransform
规则后,转换后的请求将与所有其他规则进行匹配:
E.g., with the following rules:
例如,具有以下规则:
||example.com^$urltransform=/firstpath/secondpath/
||example.com/secondpath^
the request to https://example.com/firstpath
will be blocked.
对https://example.com/firstpath
的请求将被阻止。
Disabling $urltransform
rules
禁用$urltransform
规则
@@||example.org^$urltransform
will disable all$urltransform
rules matching||example.org^
.@@||example.org^$urltransform
将禁用所有匹配||example.org^
$urltransform
规则。@@||example.org^$urltransform=/Z/Y/
will disable the rule with$urltransform=/Z/Y/
for any request matching||example.org^
.
@@||example.org^$urltransform=/Z/Y/
对于任何匹配||example.org^
请求,将禁用$urltransform=/Z/Y/
规则。
$urltransform
rules can also be disabled by $document
and $urlblock
exception rules. But basic exception rules without modifiers do not do that. For example, @@||example.com^
will not disable $urltransform=/X/Y/
for requests to example.com, but @@||example.com^$urlblock
will.$urltransform
规则也可以通过$document
和$urlblock
异常规则禁用。但不带修饰符的基本异常规则则不能做到这一点。例如, @@||example.com^
不会禁用$urltransform=/X/Y/
对example.com的请求,但@@||example.com^$urlblock
会。
Rules with the $urltransform
modifier can only be used in trusted filters.
带有$urltransform
修饰符的规则只能在受信任的过滤器中使用。
noop
noop
modifier does nothing and can be used solely to increase rules' readability. It consists of a sequence of underscore characters (_
) of arbitrary length and can appear in a rule as often as needed.noop
修饰符不执行任何操作,只能用于增加规则的可读性。它由一系列任意长度的下划线字符 ( _
) 组成,并且可以根据需要多次出现在规则中。
Examples 示例
||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party
Rules with noop
modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有noop
修饰符的规则。
$empty
(deprecated)
$empty
(已弃用)
This modifier is deprecated in favor of the $redirect
modifier.
Rules with $empty
are still supported and being converted into $redirect=nooptext
now
but the support shall be removed in the future.
该修饰符已被弃用,取而代之的是$redirect
修饰符。带有$empty
规则仍然受支持,并且现在正在转换为$redirect=nooptext
但将来将删除该支持。
Usually, blocked requests look like a server error to browser. If you use $empty
modifier, AdGuard will emulate a blank response from the server with200 OK
status.
通常,被阻止的请求对于浏览器来说看起来像是服务器错误。如果您使用$empty
修饰符,AdGuard 将模拟来自服务器的空白响应,状态为200 OK
。
Examples 示例
||example.org^$empty
returns an empty response to all requests toexample.org
and all subdomains.||example.org^$empty
对example.org
和所有子域的所有请求返回空响应。
Rules with $empty
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard for iOS 和 AdGuard for Safari 不支持带有$empty
修饰符的规则。
$mp4
(deprecated)
$mp4
(已弃用)
This modifier is deprecated in favor of the $redirect
modifier.
Rules with $mp4
are still supported and being converted into $redirect=noopmp4-1s,media
now
but the support shall be removed in the future.
该修饰符已被弃用,取而代之的是$redirect
修饰符。 $mp4
的规则仍然受支持,并转换为$redirect=noopmp4-1s,media
现在,但将来将删除该支持。
As a response to blocked request AdGuard returns a short video placeholder.
作为对被阻止请求的响应,AdGuard 返回一个短视频占位符。
Examples 示例
||example.com/videos/$mp4
blocks all video downloads from||example.com/videos/*
and changes the response to a video placeholder.||example.com/videos/$mp4
阻止来自||example.com/videos/*
的所有视频下载,并更改对视频占位符的响应。
Rules with $mp4
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard for iOS 和 AdGuard for Safari 不支持带有$mp4
修饰符的规则。
Rule priorities 规则优先级
Each rule has its own priority, which is necessary when several rules match the request and the filtering engine needs to select one of them. Priority is measured by a positive integer.
每个规则都有自己的优先级,当有多个规则与请求匹配并且过滤引擎需要选择其中之一时,这是必要的。优先级用正整数来衡量。
When two rules with the same priority match the same request, the filter engine implementation determines which one is chosen.
当具有相同优先级的两个规则匹配相同的请求时,过滤器引擎实现确定选择哪一个。
The concept of rule priorities becomes increasingly important in light of Manifest V3, as the existing rules need to be converted to declarativeNetRequest rules.
鉴于 Manifest V3,规则优先级的概念变得越来越重要,因为现有规则需要转换为 declarativeNetRequest 规则。
Priority calculation 优先级计算
To calculate priority, we've categorized modifiers into different groups. These groups are ranked based on their priority, from lowest to highest. A modifier that significantly narrows the scope of a rule adds more weight to its total priority.
为了计算优先级,我们将修饰符分为不同的组。这些组根据其优先级从最低到最高进行排名。显着缩小规则范围的修饰符会增加其总优先级的权重。
Conversely, if a rule applies to a broader range of requests, its priority decreases.
相反,如果规则适用于更广泛的请求,则其优先级会降低。
It's worth noting that there are cases where a single-parameter modifier has a higher priority than multi-parameter ones. For instance, in the case of $domain=example.com|example.org
, a rule that includes two domains has a slightly broader effective area than a rule with one specified domain, therefore its priority is lower.
值得注意的是,在某些情况下,单参数修饰符的优先级高于多参数修饰符。例如,在以下情况 $domain=example.com|example.org
,包含两个域的规则比包含一个指定域的规则的有效区域稍宽,因此其优先级较低。
The base priority of any rule is 1. If the calculated priority is a floating-point number, it will be rounded up to the smallest integer greater than or equal to the calculated priority.
任何规则的基本优先级都是1。如果计算出的优先级是浮点数,则会向上舍入到大于或等于计算出的优先级的最小整数。
- The concept of priority has been introduced in TSUrlFilter v2.1.0 and CoreLibs v1.13. Before that AdGuard didn't have any special priority computation algorithm and collisions handling could be different depending on AdGuard product and version.
优先级的概念已在TSUrlFilter v2.1.0 和CoreLibs v1.13 中引入。在此之前,AdGuard 没有任何特殊的优先级计算算法,并且冲突处理可能会根据 AdGuard 产品和版本的不同而有所不同。 - AdGuard for iOS, Safari, and AdGuard Content Blocker rely on the browsers implementation and they cannot follow the rules specified here.
AdGuard for iOS、Safari 和 AdGuard Content Blocker 依赖于浏览器实现,它们无法遵循此处指定的规则。
Modifier aliases (1p
, 3p
, etc.) are not included in these categories, however, they are utilized within the engine to compute the rule priority.
修饰符别名( 1p
、 3p
等)不包含在这些类别中,但是,它们在引擎中用于计算规则优先级。
Basic modifiers, the presence of each adds 1 to the priority
基本修饰符,每个修饰符的存在都会使优先级加 1
$app
with negated applications using~
,$app
与使用~
否定应用程序,$denyallow
,$denyallow
,$domain
with negated domains using~
,$domain
带有使用~
的否定域,$match-case
,$match-case
,$method
with negated methods using~
,$method
带有使用~
的否定方法,$strict-first-party
,$strict-first-party
,$strict-third-party
,$strict-third-party
,$third-party
,$third-party
,$to
,$to
,- restricted content-types with
~
.
用~
限制内容类型。
When dealing with a negated domain, app, method, or content-type, we add 1 point for the existence of the modifier itself, regardless of the quantity of negated domains or content-types. This is because the rule's scope is already infinitely broad.
当处理否定域、应用程序、方法或内容类型时,我们会为修饰符本身的存在添加1 分,无论否定域或内容类型的数量如何。这是因为该规则的范围已经无限广泛。
Put simply, by prohibiting multiple domains, content-types, methods or apps, the scope of the rule becomes only minimally smaller.
简而言之,通过禁止多个域、内容类型、方法或应用程序,规则的范围只会变得最小。
Defined content-type modifiers, defined methods, defined headers, $all, $popup, specific exceptions
定义的内容类型修饰符、定义的方法、定义的标头、$all、$popup、特定例外
All valid content types: 所有有效的内容类型:
$document
,$document
,$font
,$font
,$image
,$image
,$media
,$media
,$object
,$object
,$other
,$other
,$ping
,$ping
,$script
,$script
,$stylesheet
,$stylesheet
,$subdocument
,$subdocument
,$websocket
,$websocket
,$xmlhttprequest
;$xmlhttprequest
;
This also includes rules that implicitly add all content types:
这还包括隐式添加所有内容类型的规则:
Or rules that implicitly add the modifier $document
:
或者隐式添加修饰符$document
的规则:
Or some specific exceptions that implicitly add $document,subdocument
:
或者一些隐式添加$document,subdocument
的特定异常:
$content
,$content
,$elemhide
,$elemhide
,$extension
,$extension
,$genericblock
,$genericblock
,$generichide
,$generichide
,$jsinject
,$jsinject
,$specifichide
,$specifichide
,$urlblock
;$urlblock
;
Or allowed methods via $method
.
或者通过$method
允许的方法。
Or rules with $header
.
或者使用$header
进行规则。
The presence of any content-type modifiers adds (50 + 50 / N)
, where N
is the number of modifiers present, for example:
||example.com^$image,script
will add 50 + 50 / 2 = 50 + 25 = 75
to the total weight of the rule.
任何内容类型修饰符的存在都会增加(50 + 50 / N)
,其中N
是存在的修饰符的数量,例如:
||example.com^$image,script
会将50 + 50 / 2 = 50 + 25 = 75
添加到规则的总权重中。
The $all
also belongs to this category, because it implicitly adds all content type modifiers,
e.g., $document,subdocument,image,script,media,<etc>
+ $popup
.$all
也属于此类别,因为它隐式添加所有内容类型修饰符,例如, $document,subdocument,image,script,media,<etc>
+ $popup
。
The $popup
also belongs to this category, because it implicitly adds the modifier $document
.
Similarly, specific exceptions add $document,subdocument
.$popup
也属于此类,因为它隐式添加了修饰符$document
。同样,特定异常添加$document,subdocument
。
If there is a $method
modifier in the rule with allowed methods it adds (50 + 50 / N)
, where N
is the number of methods allowed, for example:
||example.com^$method=GET|POST|PUT
will add 50 + 50 / 3 = 50 + 16.6 = 67
to the total weight of the rule.
如果规则中存在允许方法的$method
修饰符,则会添加(50 + 50 / N)
,其中N
是允许的方法数量,例如:
||example.com^$method=GET|POST|PUT
会将50 + 50 / 3 = 50 + 16.6 = 67
添加到规则的总权重中。
If there is a $header
modifier in the rule, it adds 50
.
如果规则中有$header
修饰符,则会添加50
。
$domain
or $app
with allowed domains or applications
具有允许的域或应用程序的$domain
或$app
Specified domains through $domain
or specified applications through $app
add 100 + 100 / N
, where N
is the number of modifier values for example:
||example.com^$domain=example.com|example.org|example.net
will add 100 + 100 / 3 = 134.3 = 135
or
||example.com^$app=org.example.app1|org.example.app2
will add 100 + 100 / 2 = 151
or
||example.com^$domain=example.com,app=org.example.app1|org.example.app2
will add 100 + 100/1
($domain part) and 100 + 100/2
($app part), totaling 350
.
通过$domain
指定的域或通过$app
指定的应用程序添加100 + 100 / N
,其中N
是修饰符值的数量,例如:
||example.com^$domain=example.com|example.org|example.net
将加上100 + 100 / 3 = 134.3 = 135
或
||example.com^$app=org.example.app1|org.example.app2
将加上100 + 100 / 2 = 151
或
||example.com^$domain=example.com,app=org.example.app1|org.example.app2
将添加100 + 100/1
($domain 部分)和100 + 100/2
($app 部分),总计350
。
Modifier values that are regexps or tld will be interpreted as normal entries of the form example.com
and counted one by one, for example:
||example.com^$domain=example.*
will add 100 + 100 / 1 = 200
or
||example.com^$domain=example.*|adguard.*
will add 100 + 100 / 2 = 150
.
regexp 或 tld 修饰符值将被解释为example.com
形式的正常条目并一一计数,例如:
||example.com^$domain=example.*
将加上100 + 100 / 1 = 200
或
||example.com^$domain=example.*|adguard.*
将添加100 + 100 / 2 = 150
。
$redirect
rules
$redirect
规则
Each of which adds 10^3
to rule priority.
每个规则优先级都会增加10^3
。
Specific exceptions 具体例外情况
$content
,$content
,$elemhide
,$elemhide
,$extension
,$extension
,$genericblock
,$genericblock
,$generichide
,$generichide
,$jsinject
,$jsinject
,$specifichide
,$specifichide
,$urlblock
;$urlblock
;
Each of which adds 10^4
to the priority.
每一项都会给优先级增加10^4
。
As well as exception with $document modifier
: because it's an alias for $elemhide,content,jsinject,urlblock,extension
.
It will add 10^4
for each modifier from the top list, 10^4 * 5
in total.$document modifier
也有例外:因为它是 $elemhide,content,jsinject,urlblock,extension
。它将为顶部列表中的每个修饰符添加10^4
,总共10^4 * 5
。
In addition, each of these exceptions implicitly adds the two allowed content-type modifiers $document,subdocument
.
此外,每个异常都隐式添加两个允许的内容类型修饰符$document,subdocument
。
Allowlist rules 允许名单规则
Modifier @@
adds 10^5
to rule priority.
修饰符@@
将10^5
添加到规则优先级。
$important
rules
$important
规则
Modifier $important
adds 10^6
to rule priority.
修饰符$important
为规则优先级添加10^6
。
Rules for which there is no priority weight
没有优先权重的规则
Other modifiers, which are supposed to perform additional post- or pre-processing of requests,
do not add anything to the rules priority.
其他修饰符应该对请求执行额外的后处理或预处理,不会向规则优先级添加任何内容。
The $replace
modifier takes precedence over all blocking rules of categories 1-3, as well as exception rules from categories 3-5, except $content
, because an exception with the $content
modifier overrides all $replace
rules.$replace
修饰符优先于类别 1-3 的所有阻止规则以及类别 3-5 的异常规则( $content
除外),因为带有$content
修饰符的异常会覆盖所有$replace
规则。
Examples 示例
||example.com^
Weight of the rule without modifiers:
1
.
没有修饰符的规则的权重:1
。||example.com^$match-case
Rule weight: base weight + weight of the modifier from category 1:
1 + 1 = 2
.
规则权重:基础权重 +类别 1中修饰符的权重:1 + 1 = 2
。||example.org^$removeparam=p
Rule weight: base weight + 0, since $removeparam is not involved in the priority calculation:
1 + 0 = 1
.
规则权重:基础权重+0,因为不涉及$removeparam 在优先级计算中:1 + 0 = 1
。||example.org^$document,redirect=nooptext
Rule weight: base weight + allowed content type, category 3 + $redirect from category 6:
1 + (100 + 100 / 1) + 1000 = 1201
.
规则权重:基本权重 + 允许的内容类型,类别 3 + $从类别 6重定向:1 + (100 + 100 / 1) + 1000 = 1201
。@@||example.org^$removeparam=p,document
Rule weight: base weight + allowlist rule, category 5 + 0 because $removeparam is not involved in the priority calculation + allowed content type, category 2:
1 + 10000 + 0 + (50 + 50 / 1) = 10101
.
规则权重:基础权重 + 白名单规则,类别 5 + 0 因为 $removeparam不参与优先级计算 + 允许的内容类型,类别 2 :1 + 10000 + 0 + (50 + 50 / 1) = 10101
。@@||example.com/ad/*$domain=example.org|example.net,important
Rule weight: base weight + allowlist rule, category 5 + important rule, category 7 + allowed domains, category 3:
1 + 10000 + 1000000 + (100 + 100 / 2) = 1010152
.
规则权重:基础权重+白名单规则,类别5+重要规则, 类别 7 + 允许的域,类别 3 :1 + 10000 + 1000000 + (100 + 100 / 2) = 1010152
.@@||example.org^$document
without additional modifiers is an alias for@@||example.com^$elemhide,content,jsinject,urlblock,extension
不带附加修饰符的@@||example.org^$document
是以下的别名@@||example.com^$elemhide,content,jsinject,urlblock,extension
Rule weight: base weight + specific exceptions, category 4 + two allowed content types (document and subdocument), category 2:
1 + 10000 * 4 + (50 + 50 / 2) = 40076
.
规则权重:基本权重 + 特定例外,类别 4 + 两种允许的内容类型(文档和子文档),类别 2 :1 + 10000 * 4 + (50 + 50 / 2) = 40076
.*$script,domain=a.com,denyallow=x.com|y.com
Rule weight: base weight + allowed content type, category 2 + allowed domain, category 3 + denyallow, category 1:
1 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303
.
规则权重:基础权重+允许的内容类型,类别2+允许的域, 类别 3 + 拒绝,类别 1 :1 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303
.||example.com^$all
— alias to||example.com^$document,subdocument,image,script,media,etc. + $popup
||example.com^$all
— 别名||example.com^$document,subdocument,image,script,media,etc. + $popup
Rule weight: base weight + popup (category 1) + allowed content types (category 2):
1 + 1 + (50 + 50/12) = 55
.
规则权重:基本权重 + 弹出窗口(类别 1 )+ 允许的内容类型(类别 2 ):1 + 1 + (50 + 50/12) = 55
。
Non-basic rules 非基本规则
However, basic rules may not be enough to block ads.
Sometimes you need to hide an element or change part of the HTML code of a web page without breaking anything.
The rules described in this section are created specifically for this purpose.
然而,基本规则可能不足以阻止广告。有时您需要隐藏某个元素或更改网页的部分 HTML 代码而不破坏任何内容。本节中描述的规则是专门为此目的而创建的。
- ✅ — fully supported ✅ — 完全支持
- ❌ — not supported ❌ — 不支持
Cosmetic rules 化妆品规则
Work with non-basic rules requires the basic knowledge of HTML and CSS. So, if you want to learn how to make such rules, we recommend to get acquainted with this documentation.
使用非基本规则需要 HTML 和 CSS 的基本知识。因此,如果您想学习如何制定此类规则,我们建议您熟悉此文档。
Element hiding rules 元素隐藏规则
Element hiding rules are used to hide the elements of web pages. It is similar to applying { display: none; }
style to selected element.
元素隐藏规则用于隐藏网页的元素。它类似于应用{ display: none; }
选定元素的样式。
Element hiding rules may operate differently depending on the platform.
元素隐藏规则的操作方式可能因平台而异。
Syntax 句法
rule = [domains] "##" selector
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS selector, defines the elements to be hidden.selector
— CSS 选择器,定义要隐藏的元素。domains
— domain restriction for the rule.domains
— 规则的域限制。
If you want to limit the rule application area to certain domains, just enter them separated with commas. For example: example.org,example.com##selector
.
如果您想将规则应用范围限制在某些域,只需输入它们并用逗号分隔即可。例如: example.org,example.com##selector
。
This rule will be also applied to all subdomains of example.org
and example.com
.
此规则也将应用于example.org
和example.com
的所有子域。
If you want the rule not to be applied to certain domains, start a domain name with ~
sign. For example:
~example.org##selector
.
如果您希望规则不应用于某些域,请以~
符号开头的域名。例如:
~example.org##selector
。
You can use both approaches in a single rule. For example, example.org,~subdomain.example.org##domain
will work for example.org
and all subdomains, except subdomain.example.org
.
您可以在单个规则中使用这两种方法。例如, example.org,~subdomain.example.org##domain
适用于example.org
和所有子域,除了subdomain.example.org
。
Element hiding rules are not dependent on each other. If there is a rule example.org##selector
in the filter and you add ~example.org##selector
both rules will be applied independently.
元素隐藏规则彼此不依赖。如果过滤器中存在规则example.org##selector
并且您添加~example.org##selector
这两个规则将独立应用。
Examples 示例
example.com##div.textad
— hides adiv
with the classtextad
atexample.com
and all subdomains.example.com##div.textad
— 隐藏example.com
和所有子域中包含textad
类的div
。example.com,example.org###adblock
— hides an element with attributeid
equalsadblock
atexample.com
,example.org
and all subdomains.
example.com,example.org###adblock
— 在example.com
、example.org
和所有子域中隐藏属性id
等于adblock
元素。~example.com##.textad
— hides an element with the classtextad
at all domains, exceptexample.com
and its subdomains.~example.com##.textad
— 在所有域中隐藏具有类textad
的元素,除了example.com
及其子域。
Limitations 局限性
Safari does not support both allowed and disallowed domains. So the rules like example.org,~foo.example.org##.textad
are invalid in AdGuard for Safari.
Safari 不支持允许和不允许的域。所以规则就像 example.org,~foo.example.org##.textad
在 AdGuard for Safari 中无效。
Exceptions 例外情况
Exceptions can disable some rules on particular domains. They are very similar to usual exception rules, but instead of ##
you have to use #@#
.
例外可能会禁用特定域上的某些规则。它们与通常的异常规则非常相似,但您必须使用##
而不是#@#
。
For example, there is a rule in filter:
例如filter中有一条规则:
##.textad
If you want to disable it for example.com
, you can create an exception rule:
如果您想对example.com
禁用它,您可以创建一个例外规则:
example.com#@#.textad
Sometimes, it may be necessary to disable all restriction rules. For example, to conduct tests. To do this, use the exclusion rule without specifying a domain. It will completely disable matching CSS elemhide rule on ALL domains:
有时,可能需要禁用所有限制规则。例如,进行测试。为此,请使用排除规则而不指定域。它将完全禁用所有域上的匹配 CSS elemhide 规则:
#@#.textad
The same can be achieved by adding this rule:
通过添加此规则可以实现相同的效果:
*#@#.textad
We recommend to use this kind of exceptions only if it is not possible to change the hiding rule itself. In other cases it is better to change the original rule, using domain restrictions.
我们建议仅当无法更改隐藏规则本身时才使用此类例外。在其他情况下,最好使用域限制来更改原始规则。
CSS rules CSS 规则
Sometimes, simple hiding of an element is not enough to deal with advertising. For example, blocking an advertising element can just break the page layout. In this case AdGuard can use rules that are much more flexible than hiding rules.
有时,简单地隐藏元素不足以处理广告。例如,屏蔽广告元素只会破坏页面布局。在这种情况下,AdGuard 可以使用比隐藏规则灵活得多的规则。
With these rules you can basically add any CSS styles to the page.
通过这些规则,您基本上可以向页面添加任何 CSS 样式。
Syntax 句法
rule = [domains] "#$#" selector "{" style "}"
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS selector, that defines the elements we want to apply the style to.selector
— CSS 选择器,定义我们想要应用样式的元素。domains
— domain restriction for the rule. Same principles as in element hiding rules.domains
— 规则的域限制。与元素隐藏规则中的原理相同。style
— CSS style, that we want to apply to selected elements.style
— CSS 样式,我们想要应用于选定的元素。
Examples 示例
example.com#$#body { background-color: #333!important; }
This rule will apply a style background-color: #333!important;
to the body
element at example.com
and all subdomains.
该规则将应用一种样式 background-color: #333!important;
到example.com
和所有子域的body
元素。
Exceptions 例外情况
Just like with element hiding, there is a type of rules that disable the selected CSS style rule for particular domains.
Exception rule syntax is almost the same, you just have to change #$#
to #@$#
.
就像元素隐藏一样,有一类规则可以禁用特定域的选定 CSS 样式规则。异常规则语法几乎相同,只需将#$#
更改为#@$#
。
For example, there is a rule in filter:
例如filter中有一条规则:
#$#.textad { visibility: hidden; }
If you want to disable it for example.com
, you can create an exception rule:
如果您想对example.com
禁用它,您可以创建一个例外规则:
example.com#@$#.textad { visibility: hidden; }
We recommend to use this kind of exceptions only if it is not possible to change the CSS rule itself.
In other cases it is better to change the original rule, using domain restrictions.
我们建议仅当无法更改 CSS 规则本身时才使用此类例外。在其他情况下,最好使用域限制来更改原始规则。
Styles that lead to loading any resource are forbidden.
Basically, it means that you cannot use any <url>
type of value in the style.
禁止导致加载任何资源的样式。基本上,这意味着您不能在样式中使用任何<url>
类型的值。
CSS rules are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持 CSS 规则。
CSS rules may operate differently depending on the platform.
CSS 规则的运行方式可能因平台而异。
Extended CSS selectors 扩展 CSS 选择器
- Limitations 局限性
- Pseudo-class
:has()
伪类:has()
- Pseudo-class
:contains()
伪类:contains()
- Pseudo-class
:matches-css()
伪类:matches-css()
- Pseudo-class
:matches-attr()
伪类:matches-attr()
- Pseudo-class
:matches-property()
伪类:matches-property()
- Pseudo-class
:xpath()
伪类:xpath()
- Pseudo-class
:nth-ancestor()
伪类:nth-ancestor()
- Pseudo-class
:upward()
伪类:upward()
- Pseudo-class
:remove()
and pseudo-propertyremove
伪类:remove()
和伪属性remove
- Pseudo-class
:is()
伪类:is()
- Pseudo-class
:not()
伪类:not()
- Pseudo-class
:if-not()
(removed)
伪类:if-not()
(已删除)
CSS 3.0 is not always enough to block ads. To solve this problem AdGuard extends CSS capabilities by adding support for the new pseudo-elements. We have developed a separate open-source library for non-standard element selecting and applying CSS styles with extended properties.
CSS 3.0 并不总是足以阻止广告。为了解决这个问题,AdGuard 通过添加对新伪元素的支持来扩展 CSS 功能。我们开发了一个单独的开源库,用于非标准元素选择和应用具有扩展属性的 CSS 样式。
The idea of extended capabilities is an opportunity to match DOM elements with selectors based on their own representation (style, text content, etc.) or relations with other elements. There is also an opportunity to apply styles with non-standard CSS properties.
扩展功能的想法是根据 DOM 元素自身的表示(样式、文本内容等)或与其他元素的关系将 DOM 元素与选择器进行匹配。还有机会应用具有非标准 CSS 属性的样式。
Application area 应用领域
Extended selectors can be used in any cosmetic rule, whether they are element hiding rules or CSS rules.
扩展选择器可以在任何修饰规则中使用,无论它们是元素隐藏规则还是CSS 规则。
Rules with extended CSS selectors are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持具有扩展 CSS 选择器的规则。
Syntax 句法
Regardless of the CSS pseudo-classes you are using in the rule, you can use special markers to force applying these rules by ExtendedCss. It is recommended to use these markers for all extended CSS cosmetic rules so that it was easier to find them.
无论您在规则中使用什么 CSS 伪类,您都可以使用特殊标记来强制通过 ExtendedCss 应用这些规则。建议对所有扩展 CSS 修饰规则使用这些标记,以便更容易找到它们。
The syntax for extended CSS rules:
扩展 CSS 规则的语法:
#?#
— for element hiding,#@?#
— for exceptions#?#
— 用于元素隐藏,#@?#
— 用于异常#$?#
— for CSS rules,#@$?#
— for exceptions#$?#
— 对于 CSS 规则,#@$?#
— 对于例外情况
We strongly recommend using these markers any time when you use an extended CSS selector.
我们强烈建议您在使用扩展 CSS 选择器时随时使用这些标记。
Examples 示例
example.org#?#div:has(> a[target="_blank"][rel="nofollow"])
— this rule blocks alldiv
elements containing a child node that has a link with the attributes[target="_blank"][rel="nofollow"]
. The rule applies only toexample.org
and its subdomains.
example.org#?#div:has(> a[target="_blank"][rel="nofollow"])
— 此规则阻止所有包含具有与属性链接的子节点的div
元素[target="_blank"][rel="nofollow"]
。该规则仅适用于example.org
及其子域。example.com#$?#h3:contains(cookies) { display: none!important; }
— this rule sets the styledisplay: none!important
to allh3
elements that contain the wordcookies
. The rule applies only toexample.com
and all its subdomains.
example.com#$?#h3:contains(cookies) { display: none!important; }
— 此规则设置样式display: none!important
对于所有包含单词cookies
的h3
元素。该规则仅适用于example.com
及其所有子域。example.net#?#.banner:matches-css(width: 360px)
— this rule blocks all.banner
elements with the style propertywidth: 360px
. The rule applies only toexample.net
and its subdomains.
example.net#?#.banner:matches-css(width: 360px)
— 此规则会阻止所有具有 style 属性width: 360px
的.banner
元素。该规则仅适用于example.net
及其子域。example.net#@?#.banner:matches-css(width: 360px)
— this rule will disable the previous rule.
example.net#@?#.banner:matches-css(width: 360px)
— 此规则将禁用之前的规则。
You can apply standard CSS selectors using the ExtendedCss library by using the rule marker #?#
, e.g. #?#div.banner
.
您可以通过使用规则标记#?#
(例如#?#div.banner
,使用 ExtendedCss 库应用标准 CSS 选择器。
Learn more about how to debug extended selectors.
了解有关如何调试扩展选择器的更多信息。
Some pseudo-classes do not require selector before it. Still adding the universal selector *
makes an extended selector easier to read, even though it has no effect on the matching behavior. So selector #block :has(> .inner)
works exactly like #block *:has(> .inner)
, but the second one is more obvious.
一些伪类不需要前面有选择器。仍然添加通用选择器*
使扩展选择器更易于阅读,即使它对匹配行为没有影响。因此选择器#block :has(> .inner)
的工作方式与#block *:has(> .inner)
完全相同,但第二个更明显。
Pseudo-class names are case-insensitive, e.g. :HAS()
works as :has()
. Still the lower-case names are used commonly.
伪类名称不区分大小写,例如:HAS()
与:has()
一样。但小写字母名称仍被广泛使用。
ExtendedCss Limitations 扩展 CSS 限制
CSS comments and at-rules are not supported.
不支持 CSS注释和at 规则。Specific pseudo-class may have its own limitations:
:has()
,:xpath()
,:nth-ancestor()
,:upward()
,:is()
,:not()
, and:remove()
.
具体的伪类可能有其自身的局限性::has()
、:xpath()
、:nth-ancestor()
、:upward()
、:is()
、:not()
和:remove()
。
Pseudo-class :has()
伪类:has()
Draft CSS 4.0 specification describes the :has()
pseudo-class. Unfortunately, it is not yet supported by all popular browsers.
CSS 4.0 规范草案描述了:has()
伪类。不幸的是,并非所有流行的浏览器都支持它。
Rules with the :has()
pseudo-class must use the native implementation of :has()
if they use ##
marker and if it is possible, i.e. with no other extended selectors inside. To force applying of ExtendedCss rules with :has()
, use #?#
/#$?#
marker explicitly.
如果使用##
标记并且可能的话,带有:has()
伪类的规则必须使用:has()
的本机实现,即内部没有其他扩展选择器。要通过:has()
强制应用 ExtendedCss 规则,请显式使用#?#
/ #$?#
标记。
Compatibility with other pseudo-classes
与其他伪类的兼容性
Synonyms :-abp-has()
is supported by ExtendedCss for better compatibility.
同义词:-abp-has()
由 ExtendedCss 支持以获得更好的兼容性。
:if()
is no longer supported as a synonym for :has()
.
不再支持:if()
作为:has()
同义词。
Syntax 句法
[target]:has(selector)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素selector
— required, standard or extended CSS selectorselector
— 必需的、标准的或扩展的 CSS 选择器
The pseudo-class :has()
selects the target
elements that fit to the selector
. Also the selector
can start with a combinator.
伪类:has()
选择适合selector
的target
元素。 selector
也可以从组合器开始。
A selector list can be set in selector
as well. In this case all selectors in the list are being matched for now. In the future it will be fixed for <forgiving-relative-selector-list>
as argument.
也可以在selector
中设置选择器列表。在这种情况下,列表中的所有选择器现在都会被匹配。未来将修复为 <forgiving-relative-selector-list>
作为论证。
:has()
limitations
:has()
限制
Usage of the :has()
pseudo-class is restricted for some cases (2, 3)::has()
伪类的使用在某些情况下受到限制 (2, 3) :
- disallow
:has()
inside the pseudos accepting only compound selectors;
不允许:has()
在伪类中仅接受复合选择器; - disallow
:has()
after regular pseudo-elements.
禁止在常规伪元素之后使用:has()
。
Native :has()
pseudo-class does not allow :has()
, :is()
, :where()
inside :has()
argument to avoid increasing the :has()
invalidation complexity (case 1). But ExtendedCss did not have such limitation earlier and filter lists already contain such rules, so we have not added this limitation to ExtendedCss and allow to use :has()
inside :has()
as it was possible before. To use it, just force ExtendedCss usage by setting #?#
/#$?#
rule marker.
本机:has()
伪类不允许:has()
、 :is()
、 :where()
:has()
以避免增加:has()
失效复杂性(情况 1 )。但 ExtendedCss 之前没有这样的限制,并且过滤器列表已经包含这样的规则,因此我们没有将这个限制添加到 ExtendedCss 中,并允许像以前一样在:has()
:has()
。要使用它,只需通过设置#?#
/ #$?#
规则标记来强制使用 ExtendedCss 即可。
Native implementation does not allow any usage of :scope
inside the :has()
argument ([1], [2]). Still, there are some such rules in filter lists: div:has(:scope a)
which we continue to support by simply converting them to div:has(> a)
, as it used to be done previously.
本机实现不允许在:has()
参数( [1] 、 [2] )内使用:scope
。尽管如此,过滤器列表中仍然有一些这样的规则: div:has(:scope a)
我们通过简单地将它们转换为div:has(> a)
来继续支持它们,就像以前所做的那样。
Examples 示例
div:has(.banner)
selects all div
elements which include an element with the banner
class:div:has(.banner)
选择包含带有banner
类的元素的所有div
元素:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<span class="banner">inner element</span>
</div>
div:has(> .banner)
selects all div
elements which include an banner
class element as a direct child of div
:div:has(> .banner)
选择所有包含banner
类元素的div
元素作为div
的直接子元素:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<p class="banner">child element</p>
</div>
div:has(+ .banner)
selects all div
elements preceding banner
class element which immediately follows the div
and both are children of the same parent:div:has(+ .banner)
选择紧跟在div
后面的banner
类元素之前的所有div
元素,并且两者都是同一父级的子级:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<p class="banner">adjacent sibling</p>
<span>Not selected</span>
div:has(~ .banner)
selects all div
elements preceding banner
class element which follows the div
but not necessarily immediately and both are children of the same parent:div:has(~ .banner)
选择在div
后面的banner
类元素之前的所有div
元素,但不一定是立即的,并且两者都是同一父级的子级:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<span>Not selected</span>
<p class="banner">general sibling</p>
div:has(span, .banner)
selects all div
elements which include both span
element and banner
class element:div:has(span, .banner)
选择所有div
元素,其中包括span
元素和banner
类元素:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<span>child span</span>
<p class="banner">child .banner</p>
</div>
Backward compatible syntax for :has()
is supported but not recommended.:has()
的向后兼容语法
支持但不推荐。
Pseudo-class :contains()
伪类:contains()
The :contains()
pseudo-class principle is very simple: it allows to select the elements that contain specified text or which content matches a specified regular expression. Regexp flags are supported.:contains()
伪类原理非常简单:它允许选择包含指定文本或内容与指定正则表达式匹配的元素。支持正则表达式标志。
The :contains()
pseudo-class uses the textContent
element property for matching, not the innerHTML
.:contains()
伪类使用textContent
元素属性进行匹配,而不是innerHTML
。
Compatibility with other pseudo-classes
与其他伪类的兼容性
Synonyms :-abp-contains()
and :has-text()
are supported for better compatibility.
支持同义词:-abp-contains()
和:has-text()
以实现更好的兼容性。
Syntax 句法
[target]:contains(match)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素match
— required, string or regular expression for matching elementtextContent
. Regular expression flags are supported.match
— 必需,匹配元素textContent
的字符串或正则表达式。支持正则表达式标志。
Examples 示例
For such DOM: 对于这样的 DOM:
<!-- HTML code -->
<div>Not selected</div>
<div id="match">Selected as IT contains "banner"</div>
<div>Not selected <div class="banner"></div></div>
the element div#match
can be selected by any of these extended selectors:
元素div#match
可以由以下任何扩展选择器选择:
! plain text
div:contains(banner)
! regular expression
div:contains(/as .*banner/)
! regular expression with flags
div:contains(/it .*banner/gi)
Only the div
with id=match
is selected because the next element does not contain any text, and banner
is a part of code, not a text.
仅选择id=match
的div
,因为下一个元素不包含任何文本,并且banner
是代码的一部分,而不是文本。
Backward compatible syntax for :contains()
is supported but not recommended.:contains()
的向后兼容语法
支持但不推荐。
Pseudo-class :matches-css()
伪类:matches-css()
The :matches-css()
pseudo-class allows to match the element by its current style properties. The work of the pseudo-class is based on using the Window.getComputedStyle()
method.:matches-css()
伪类允许通过元素当前的样式属性来匹配元素。伪类的工作基于使用Window.getComputedStyle()
方法。
Syntax 句法
[target]:matches-css([pseudo-element, ] property: pattern)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素pseudo-element
— optional, valid standard pseudo-element, e.g.before
,after
,first-line
, etc.pseudo-element
— 可选的、有效的标准伪元素,例如before
、after
、first-line
等。property
— required, a name of CSS property to check the element forproperty
— 必需的,用于检查元素的 CSS 属性的名称pattern
— required, a value pattern that is using the same simple wildcard matching as in the basic URL filtering rules or a regular expression. For this type of matching, AdGuard always does matching in a case-insensitive manner.pattern
— 必需,使用与基本 URL 过滤规则或正则表达式中相同的简单通配符匹配的值模式。对于这种类型的匹配,AdGuard 始终以不区分大小写的方式进行匹配。
In the case of a regular expression, the pattern looks like/regexp/
.
对于正则表达式,模式类似于/regexp/
。
Special characters escaping and unescaping
特殊字符转义和取消转义
For non-regexp patterns (
,)
,[
,]
must be unescaped, e.g. :matches-css(background-image:url(data:*))
.
对于非正则表达式模式(
, )
, [
, ]
必须不转义,例如 :matches-css(background-image:url(data:*))
。
For regexp patterns \
should be escaped, e.g. :matches-css(background-image: /^url\\("data:image\\/gif;base64.+/)
.
对于正则表达式模式\
应该转义,例如 :matches-css(background-image: /^url\\("data:image\\/gif;base64.+/)
。
Examples 示例
For such DOM: 对于这样的 DOM:
<!-- HTML code -->
<style type="text/css">
#matched::before {
content: "Block me"
}
</style>
<div id="matched"></div>
<div id="not-matched"></div>
the div
elements with pseudo-element ::before
and with specified content
property can be selected by any of these extended selectors:
具有伪元素::before
和指定content
属性的div
元素可以通过以下任何扩展选择器进行选择:
! string pattern
div:matches-css(before, content: block me)
! string pattern with wildcard
div:matches-css(before, content: block*)
! regular expression pattern
div:matches-css(before, content: /block me/)
Regexp patterns do not support flags.
正则表达式模式不支持标志。
Obsolete pseudo-classes :matches-css-before()
and :matches-css-after()
are no longer recommended but still are supported for better compatibility.
不再推荐过时的伪类:matches-css-before()
和:matches-css-after()
但仍然支持以获得更好的兼容性。
Backward compatible syntax for :matches-css()
is supported but not recommended.:matches-css()
的向后兼容语法
支持但不推荐。
Pseudo-class :matches-attr()
伪类:matches-attr()
The :matches-attr()
pseudo-class allows selecting an element by its attributes, especially if they are randomized.:matches-attr()
伪类允许通过元素的属性来选择元素,特别是当它们是随机的时。
Syntax 句法
[target]:matches-attr("name"[="value"])
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素name
— required, simple string or string with wildcard or regular expression for attribute name matchingname
— 必需的,简单字符串或带有通配符或正则表达式的字符串,用于属性名称匹配value
— optional, simple string or string with wildcard or regular expression for attribute value matchingvalue
— 可选的简单字符串或带有通配符或正则表达式的字符串,用于属性值匹配
Escaping special characters
转义特殊字符
For regexp patterns "
and \
should be escaped, e.g. div:matches-attr(class=/[\\w]{5}/)
.
对于正则表达式模式"
和\
应该被转义,例如 div:matches-attr(class=/[\\w]{5}/)
。
Examples 示例
div:matches-attr("ad-link")
selects the element div#target1
:div:matches-attr("ad-link")
选择元素div#target1
:
<!-- HTML code -->
<div id="target1" ad-link="1random23-banner_240x400"></div>
div:matches-attr("data-*"="adBanner")
selects the element div#target2
:
div:matches-attr("data-*"="adBanner")
选择元素div#target2
:
<!-- HTML code -->
<div id="target2" data-1random23="adBanner"></div>
div:matches-attr(*unit*=/^click$/)
selects the element div#target3
:
div:matches-attr(*unit*=/^click$/)
选择元素div#target3
:
<!-- HTML code -->
<div id="target3" random123-unit094="click"></div>
*:matches-attr("/.{5,}delay$/"="/^[0-9]*$/")
selects the element #target4
:
*:matches-attr("/.{5,}delay$/"="/^[0-9]*$/")
选择元素#target4
:
<!-- HTML code -->
<div>
<inner-random23 id="target4" nt4f5be90delay="1000"></inner-random23>
</div>
Regexp patterns do not support flags.
正则表达式模式不支持标志。
Pseudo-class :matches-property()
伪类:matches-property()
The :matches-property()
pseudo-class allows selecting an element by matching its properties.:matches-property()
伪类允许通过匹配元素的属性来选择元素。
Syntax 句法
[target]:matches-property("name"[="value"])
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素name
— required, simple string or string with wildcard or regular expression for element property name matchingname
— 必需的,简单字符串或带有通配符或正则表达式的字符串,用于元素属性名称匹配value
— optional, simple string or string with wildcard or regular expression for element property value matchingvalue
— 可选的简单字符串或带有通配符或正则表达式的字符串,用于元素属性值匹配
Escaping special characters
转义特殊字符
For regexp patterns "
and \
must be escaped, e.g. div:matches-property(prop=/[\\w]{4}/)
.
对于正则表达式模式"
和\
必须转义,例如 div:matches-property(prop=/[\\w]{4}/)
。
Regexp patterns are supported in name
for any property in chain, e.g. prop./^unit[\\d]{4}$/.type
.
链中任何属性的name
都支持正则表达式模式,例如prop./^unit[\\d]{4}$/.type
。
Examples 示例
An element with such properties:
具有以下属性的元素:
divProperties = {
id: 1,
check: {
track: true,
unit_2random1: true,
},
memoizedProps: {
key: null,
tag: 12,
_owner: {
effectTag: 1,
src: 'ad.com',
},
},
};
can be selected by any of these extended selectors:
可以通过以下任何扩展选择器进行选择:
div:matches-property(check.track)
div:matches-property("check./^unit_.{4,8}$/")
div:matches-property("check.unit_*"=true)
div:matches-property(memoizedProps.key="null")
div:matches-property(memoizedProps._owner.src=/ad/)
To check properties of a specific element, do the following:
要检查特定元素的属性,请执行以下操作:
- Inspect the page element or select it in
Elements
tab of browser DevTools
检查页面元素或在浏览器 DevTools 的Elements
选项卡中选择它 - Run
console.dir($0)
inConsole
tab
在Console
选项卡中运行console.dir($0)
Regexp patterns do not support flags.
正则表达式模式不支持标志。
Pseudo-class :xpath()
伪类:xpath()
The :xpath()
pseudo-class allows selecting an element by evaluating an XPath expression.:xpath()
伪类允许通过计算 XPath 表达式来选择元素。
Syntax 句法
[target]:xpath(expression)
target
- optional, standard or extended CSS selectortarget
- 可选、标准或扩展 CSS 选择器expression
— required, valid XPath expressionexpression
— 必需的、有效的 XPath 表达式
:xpath()
limitations
:xpath()
限制
target
can be omitted so it is optional. For any other pseudo-class that would mean "apply to all DOM nodes", but in case of :xpath()
it just means "apply to the whole document", and such applying slows elements selecting significantly. That's why rules like #?#:xpath(expression)
are limited to looking inside the body
tag. For example, rule #?#:xpath(//div[@data-st-area=\'Advert\'])
is parsed as #?#body:xpath(//div[@data-st-area=\'Advert\'])
.target
可以省略,因此它是可选的。对于任何其他伪类,这意味着“应用于所有DOM 节点”,但在:xpath()
的情况下,它仅意味着“应用于整个文档”,这样的应用会显着减慢元素选择速度。这就是为什么#?#:xpath(expression)
之类的规则仅限于查看body
标记内部。例如,规则 #?#:xpath(//div[@data-st-area=\'Advert\'])
被解析为 #?#body:xpath(//div[@data-st-area=\'Advert\'])
。
Extended selectors with defined target
as any selector — *:xpath(expression)
— can still be used but it is not recommended, so target
should be specified instead.
将target
定义为任何选择器的扩展选择器 — *:xpath(expression)
— 仍然可以使用,但不建议这样做,因此应指定target
。
Works properly only at the end of selector, except for pseudo-class :remove().
仅在选择器末尾才能正常工作,伪类 :remove()除外。
Examples 示例
:xpath(//*[@class="banner"])
selects the element div#target1
::xpath(//*[@class="banner"])
选择元素div#target1
:
<!-- HTML code -->
<div id="target1" class="banner"></div>
:xpath(//*[@class="inner"]/..)
selects the element div#target2
:
:xpath(//*[@class="inner"]/..)
选择元素div#target2
:
<!-- HTML code -->
<div id="target2">
<div class="inner"></div>
</div>
Pseudo-class :nth-ancestor()
伪类:nth-ancestor()
The :nth-ancestor()
pseudo-class allows to lookup the nth ancestor relative to the previously selected element.:nth-ancestor()
伪类允许查找相对于先前选择的元素的第 n 个祖先。
subject:nth-ancestor(n)
subject
— required, standard or extended CSS selectorsubject
— 必需的、标准的或扩展的 CSS 选择器n
— required, number >= 1 and < 256, distance to the needed ancestor from the element selected bysubject
n
— 必需,数字 >= 1 且 < 256,从subject
选择的元素到所需祖先的距离
Syntax 句法
subject:nth-ancestor(n)
subject
— required, standard or extended CSS selectorsubject
— 必需的、标准的或扩展的 CSS 选择器n
— required, number >= 1 and < 256, distance to the needed ancestor from the element selected bysubject
n
— 必需,数字 >= 1 且 < 256,从subject
选择的元素到所需祖先的距离
:nth-ancestor()
limitations
:nth-ancestor()
限制
The :nth-ancestor()
pseudo-class is not supported inside the argument of the :not()
pseudo-class.:nth-ancestor()
伪类在:not()
伪类的参数内不受支持。
Examples 示例
For such DOM: 对于这样的 DOM:
<!-- HTML code -->
<div id="target1">
<div class="child"></div>
<div id="target2">
<div>
<div>
<div class="inner"></div>
</div>
</div>
</div>
</div>
.child:nth-ancestor(1)
selects the element div#target1
,
div[class="inner"]:nth-ancestor(3)
selects the element div#target2
..child:nth-ancestor(1)
选择元素div#target1
,
div[class="inner"]:nth-ancestor(3)
选择元素div#target2
。
Pseudo-class :upward()
伪类:upward()
The :upward()
pseudo-class allows to lookup the ancestor relative to the previously selected element.:upward()
伪类允许查找相对于先前选择的元素的祖先。
Syntax 句法
subject:upward(ancestor)
subject
— required, standard or extended CSS selectorsubject
— 必需的、标准的或扩展的 CSS 选择器ancestor
— required, specification for the ancestor of the element selected bysubject
, can be set as:ancestor
— 必需,指定subject
所选择的元素的祖先,可以设置为:- number >= 1 and < 256 for distance to the needed ancestor, same as
:nth-ancestor()
number >= 1 and < 256 表示到所需祖先的距离,与:nth-ancestor()
相同 - standard CSS selector for matching closest ancestor
用于匹配最近祖先的标准 CSS 选择器
- number >= 1 and < 256 for distance to the needed ancestor, same as
:upward()
limitations
:upward()
限制
The :upward()
pseudo-class is not supported inside the argument of the :not()
pseudo-class.:upward()
:not()
伪类。
Examples 示例
For such DOM: 对于这样的 DOM:
<!-- HTML code -->
<div id="target1" data="true">
<div class="child"></div>
<div id="target2">
<div>
<div>
<div class="inner"></div>
</div>
</div>
</div>
</div>
.inner:upward(div[data])
selects the element div#target1
,
.inner:upward(div[id])
selects the element div#target2
,
.child:upward(1)
selects the element div#target1
,
.inner:upward(3)
selects the element div#target2
..inner:upward(div[data])
选择元素div#target1
,
.inner:upward(div[id])
选择元素div#target2
,
.child:upward(1)
选择元素div#target1
,
.inner:upward(3)
选择元素div#target2
。
Pseudo-class :remove()
and pseudo-property remove
伪类:remove()
和伪属性remove
Sometimes, it is necessary to remove a matching element instead of hiding it or applying custom styles. In order to do it, you can use the :remove()
pseudo-class as well as the remove
pseudo-property.
有时,有必要删除匹配的元素,而不是隐藏它或应用自定义样式。为此,您可以使用:remove()
伪类以及remove
伪属性。
Pseudo-class :remove()
can be placed only at the end of a selector.
伪类:remove()
只能放置在选择器的末尾。
Syntax 句法
! pseudo-class
selector:remove()
! pseudo-property
selector { remove: true; }
selector
— required, standard or extended CSS selectorselector
— 必需的、标准的或扩展的 CSS 选择器
:remove()
and remove
limitations
:remove()
并remove
限制
The :remove()
pseudo-class is limited to work properly only at the end of selector.:remove()
伪类仅限于仅在选择器末尾才能正常工作。
For applying the :remove()
pseudo-class to any element, the universal selector *
should be used. Otherwise such extended selector may be considered as invalid, e.g. .banner > :remove()
is not valid for removing any child element of banner
class element, so it should look like .banner > *:remove()
.
要将:remove()
伪类应用于任何元素,应使用通用选择器*
。否则,此类扩展选择器可能会被视为无效,例如.banner > :remove()
对于删除banner
类元素的任何子元素无效,因此它应该类似于.banner > *:remove()
。
If the :remove()
pseudo-class or the remove
pseudo-property is used, all style properties are ignored except for the debug
pseudo-property.
如果使用:remove()
伪类或remove
伪属性,则除debug
伪属性之外的所有样式属性都将被忽略。
Examples 示例
div.banner:remove()
div:has(> div[ad-attr]):remove()
div:contains(advertisement) { remove: true; }
div[class]:has(> a > img) { remove: true; }
Rules with the remove
pseudo-property must use #$?#
marker: $
for CSS-style rule syntax, ?
for ExtendedCss syntax.
具有remove
伪属性的规则必须使用#$?#
标记: $
用于 CSS 样式规则语法, ?
对于 ExtendedCss 语法。
Pseudo-class :is()
伪类:is()
The :is()
pseudo-class allows to match any element that can be selected by any of selectors passed to it. Invalid selectors are skipped and the pseudo-class deals with valid ones with no error thrown. Our implementation of the native :is()
pseudo-class.:is()
伪类允许匹配可由传递给它的任何选择器选择的任何元素。无效的选择器会被跳过,伪类会处理有效的选择器而不会抛出错误。我们对本机:is()
伪类的实现。
Syntax 句法
[target]:is(selectors)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素selectors
— forgiving selector list of standard or extended selectors. For extended selectors, only compound selectors are supported, not complex.selectors
—允许标准或扩展选择器的选择器列表。对于扩展选择器,仅支持复合选择器,不支持复杂选择器。
:is()
limitations
:is()
限制
Rules with the :is()
pseudo-class must use the native implementation of :is()
if rules use ##
marker and it is possible, i.e. with no other extended selectors inside. To force applying ExtendedCss rules with :is()
, use #?#
/#$?#
marker explicitly.
如果规则使用##
标记且可能,即内部没有其他扩展选择器,则具有:is()
伪类的规则必须使用:is()
的本机实现。要使用:is()
强制应用 ExtendedCss 规则,请显式使用#?#
/ #$?#
标记。
If the :is()
pseudo-class argument selectors
is an extended selector, due to the way how the :is()
pseudo-class is implemented in ExtendedCss v2.0, it is impossible to apply it to the top DOM node which is html
, i.e. #?#html:is(<extended-selectors>)
does not work. So if target
is not defined or defined as the universal selector *
, the extended pseudo-class applying is limited to html
's children, e.g. rules #?#:is(...)
and #?#*:is(...)
are parsed as #?#html *:is(...)
. Please note that there is no such limitation for a standard selector argument, i.e. #?#html:is(.locked)
works fine.
如果:is()
伪类参数selectors
是扩展选择器,则由于:is()
伪类在 ExtendedCss v2.0 中的实现方式,无法将其应用于顶部 DOM 节点,即html
#?#html:is(<extended-selectors>)
不起作用。因此,如果target
未定义或定义为通用选择器*
,则扩展伪类应用仅限于html
的子级,例如规则#?#:is(...)
和#?#*:is(...)
被解析为#?#html *:is(...)
。请注意,标准选择器参数没有这样的限制,即#?#html:is(.locked)
工作正常。
Complex selectors with extended pseudo-classes are not supported as selectors
argument for :is()
pseudo-class, only compound ones are allowed. Check examples below for more details.
不支持具有扩展伪类的复杂选择器作为:is()
伪类的selectors
参数,仅允许复合选择器。查看下面的示例以了解更多详细信息。
Examples 示例
#container *:is(.inner, .footer)
selects only the element div#target1
:
#container *:is(.inner, .footer)
仅选择元素div#target1
:
<!-- HTML code -->
<div id="container">
<div data="true">
<div>
<div id="target1" class="inner"></div>
</div>
</div>
</div>
Due to limitations :is(*:not([class]) > .banner)'
does not work
but :is(*:not([class]):has(> .banner))
can be used instead of it to select the element div#target2
:
由于限制 :is(*:not([class]) > .banner)'
不起作用但是 :is(*:not([class]):has(> .banner))
可以用来代替它来选择元素div#target2
:
<!-- HTML code -->
<span class="span">text</span>
<div id="target2">
<p class="banner">inner paragraph</p>
</div>
Pseudo-class :not()
伪类:not()
The :not()
pseudo-class allows to select elements which are not matched by selectors passed as argument. Invalid argument selectors are not allowed and error is to be thrown. Our implementation of the :not()
pseudo-class.:not()
伪类允许选择与作为参数传递的选择器不匹配的元素。不允许使用无效的参数选择器,并且会抛出错误。我们的:not()
伪类的实现。
Syntax 句法
[target]:not(selectors)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementtarget
— 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素selectors
— list of standard or extended selectorsselectors
— 标准或扩展选择器列表
:not()
limitations
:not()
限制
Rules with the :not()
pseudo-class must use the native implementation of :not()
if rules use ##
marker and it is possible, i.e. with no other extended selectors inside. To force applying ExtendedCss rules with :not()
, use #?#
/#$?#
marker explicitly.
如果规则使用##
标记且可能,即内部没有其他扩展选择器,则具有:not()
伪类的规则必须使用:not()
的本机实现。要使用:not()
强制应用 ExtendedCss 规则,请显式使用#?#
/ #$?#
标记。
If the :not()
pseudo-class argument selectors
is an extended selector, due to the way how the :not()
pseudo-class is implemented in ExtendedCss v2.0, it is impossible to apply it to the top DOM node which is html
, i.e. #?#html:not(<extended-selectors>)
does not work. So if target
is not defined or defined as the universal selector *
, the extended pseudo-class applying is limited to html
's children, e.g. rules #?#:not(...)
and #?#*:not(...)
are parsed as #?#html *:not(...)
. Please note that there is no such limitation for a standard selector argument, i.e. #?#html:not(.locked)
works fine.
如果:not()
伪类参数selectors
是扩展选择器,由于:not()
伪类在 ExtendedCss v2.0 中的实现方式,不可能将其应用于顶部 DOM 节点,即html
#?#html:not(<extended-selectors>)
不起作用。因此,如果target
未定义或定义为通用选择器*
,则扩展伪类应用仅限于html
的子级,例如规则#?#:not(...)
和#?#*:not(...)
被解析为#?#html *:not(...)
。请注意,标准选择器参数没有这样的限制,即#?#html:not(.locked)
工作正常。
The :not()
is considered as a standard CSS pseudo-class inside the argument of the :upward()
pseudo-class because :upward()
supports only standard selectors.:not()
被视为:upward()
伪类参数内的标准 CSS 伪类,因为:upward()
仅支持标准选择器。
"Up-looking" pseudo-classes which are :nth-ancestor()
and :upward()
are not supported inside selectors
argument for :not()
pseudo-class.:not()
伪类的selectors
参数内部不支持“向上”伪类:nth-ancestor()
和:upward()
。
Examples 示例
#container > *:not(h2, .text)
selects only the element div#target1
:#container > *:not(h2, .text)
仅选择元素div#target1
:
<!-- HTML code -->
<div id="container">
<h2>Header</h2>
<div id="target1"></div>
<span class="text">text</span>
</div>
Pseudo-class :if-not()
(removed)
伪类:if-not()
(已删除)
The :if-not()
pseudo-class is removed and is no longer supported. Rules with it are considered as invalid.:if-not()
伪类已被删除并且不再受支持。带有它的规则被认为是无效的。
This pseudo-class was basically a shortcut for :not(:has())
. It was supported by ExtendedCss for better compatibility with some filters subscriptions.
这个伪类基本上是:not(:has())
的快捷方式。它受到 ExtendedCss 的支持,以更好地兼容某些过滤器订阅。
Cosmetic rules priority 化妆品规则优先
The way element hiding and CSS rules are applied is platform-specific.
元素隐藏和CSS 规则的应用方式是特定于平台的。
In AdGuard for Windows, Mac, and Android, we use a stylesheet injected into the page. The priority of cosmetic rules is the same as any other websites' CSS stylesheet. But there is a limitation: element hiding and CSS rules cannot override inline styles. In such cases, it is recommended to use extended selectors or HTML filtering.
在适用于 Windows、Mac 和 Android 的 AdGuard 中,我们使用注入到页面中的样式表。修饰规则的优先级与任何其他网站的 CSS 样式表相同。但有一个限制:元素隐藏和CSS 规则无法覆盖内联样式。在这种情况下,建议使用扩展选择器或 HTML 过滤。
In AdGuard Browser Extension, the so called "user stylesheets" are used. They have higher priority than even the inline styles.
在 AdGuard 浏览器扩展中,使用所谓的“用户样式表”。它们的优先级甚至高于内联样式。
Extended CSS selectors use JavaScript to work and basically add an inline style themselves, therefore they can override any style.
扩展CSS选择器使用JavaScript来工作,并且基本上自己添加内联样式,因此它们可以覆盖任何样式。
HTML filtering rules HTML过滤规则
In most cases, the basis and cosmetic rules are enough to filter ads. But sometimes it is necessary to change the HTML-code of the page itself before it is loaded. This is when you need filtering rules for HTML content.
在大多数情况下,基础规则和修饰规则足以过滤广告。但有时需要在加载页面之前更改页面本身的 HTML 代码。这就是您需要 HTML 内容的过滤规则的时候。
They allow to indicate the HTML elements to be cut out before the browser loads the page.
它们允许指示在浏览器加载页面之前要剪切的 HTML 元素。
HTML filtering rules are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Firefox. Such rules do not work in extensions for other browsers because they are unable to modify content on network level.
AdGuard for Windows、AdGuard for Mac、AdGuard for Android 和 AdGuard Browser Extension for Firefox 支持 HTML 过滤规则。此类规则不适用于其他浏览器的扩展,因为它们无法修改网络级别的内容。
Syntax 句法
selector = [tagName] [attributes] [pseudoClasses]
combinator = ">"
rule = [domains] "$$" selector *(combinator selector)
domains = [domain0, domain1[, ...[, domainN]]]
attributes = "[" name0 = value0 "]" "[" name1 = value2 "]" ... "[" nameN = valueN "]"
pseudoClasses = pseudoClass *pseudoClass
pseudoClass = ":" pseudoName [ "(" pseudoArgs ")" ]
tagName
— name of the element in lower case, for example,div
orscript
.tagName
— 小写的元素名称,例如div
或script
。domains
— domain restriction for the rule. Same principles as in element hiding rule syntax.domains
— 规则的域限制。与元素隐藏规则语法中的原理相同。attributes
— a list of attributes that limit the selection of elements.name
— attribute name,value
— substring, that is contained in attribute value.attributes
— 限制元素选择的属性列表。name
— 属性名称,value
— 属性值中包含的子字符串。pseudoName
— the name of a pseudo-class.pseudoName
— 伪类的名称。pseudoArgs
— the arguments of a function-style pseudo-class.pseudoArgs
— 函数样式伪类的参数。combinator
— an operator that works similarly to the CSS child combinator: that is, theselector
on the right of thecombinator
will only match an element whose direct parent matches theselector
on the left of thecombinator
.combinator
— 与CSS 子组合器类似的操作符:也就是说,combinator
右侧的selector
将仅匹配其直接父级与combinator
左侧的selector
匹配的元素。
Examples 示例
HTML code: HTML 代码:
<script data-src="/banner.js"></script>
Rule: 规则:
example.org$$script[data-src="banner"]
This rule removes all script
elements with the attribute data-src
containing the substring banner
. The rule applies only to example.org
and all its subdomains.
此规则将删除属性data-src
包含子字符串banner
的所有script
元素。该规则仅适用于example.org
及其所有子域。
Special attributes 特殊属性
In addition to usual attributes, which value is every element checked for, there is a set of special attributes that change the way a rule works. Below there is a list of these attributes:
除了通常的属性(检查每个元素的值)之外,还有一组特殊属性可以更改规则的工作方式。下面是这些属性的列表:
tag-content
This special attribute may become unsupported in the future. Prefer using the :contains()
pseudo-class where it is available.
这个特殊属性将来可能会不受支持。最好使用:contains()
伪类(如果可用)。
This is the most frequently used special attribute. It limits selection with those elements whose innerHTML code contains the specified substring.
这是最常用的特殊属性。它限制选择那些其innerHTML 代码包含指定子字符串的元素。
You must use ""
to escape "
, for instance:
$$script[tag-content="alert(""this is ad"")"]
您必须使用""
来转义"
,例如:
$$script[tag-content="alert(""this is ad"")"]
For example, take a look at this HTML code:
例如,看一下以下 HTML 代码:
<script type="text/javascript">
document.write('<div>banner text</div>" />');
</script>
Following rule will delete all script
elements with a banner
substring in their code:
以下规则将删除代码中带有banner
字符串的所有script
元素:
$$script[tag-content="banner"]
The tag-content
special attribute must not appear in a selector to the left of a >
combinator.tag-content
特殊属性不得出现在>
组合符左侧的选择器中。
wildcard
This special attribute may become unsupported in the future. Prefer using the :contains()
pseudo-class where it is available.
这个特殊属性将来可能会不受支持。最好使用:contains()
伪类(如果可用)。
This special attribute works almost like tag-content
and allows you to check the innerHTML code of the document. Rule will check if HTML code of the element fits to the search pattern.
这个特殊属性的工作方式几乎与tag-content
类似,允许您检查文档的 insideHTML 代码。规则将检查元素的 HTML 代码是否符合搜索模式。
You must use ""
to escape "
, for instance:
$$script[wildcard=""banner""]
您必须使用""
来转义"
,例如:
$$script[wildcard=""banner""]
For example:
$$script[wildcard="*banner*text*"]
例如:
$$script[wildcard="*banner*text*"]
It checks if the element code contains the two consecutive substrings banner
and text
.
它检查元素code是否包含两个连续的子字符串banner
和text
。
The wildcard
special attribute must not appear in a selector to the left of a >
combinator.wildcard
特殊属性不得出现在>
组合符左侧的选择器中。
max-length
This special attribute may become unsupported in the future. Prefer using the :contains()
pseudo-class with a regular expression where it is available.
这个特殊属性将来可能会不受支持。最好将:contains()
伪类与可用的正则表达式一起使用。
Specifies the maximum length for content of HTML element. If this parameter is set and the content length exceeds the value, a rule does not apply to the element.
指定 HTML 元素内容的最大长度。如果设置了此参数并且内容长度超过该值,则规则不适用于该元素。
Default value 默认值
If this parameter is not specified, the max-length
is considered to be 8192.
如果不指定该参数,则认为max-length
为8192。
For example: 例如:
$$div[tag-content="banner"][max-length="400"]
This rule will remove all the div
elements, whose code contains the substring banner
and the length of which does not exceed 400
characters.
该规则将删除所有代码中包含子字符串banner
且长度不超过400
字符的div
元素。
The max-length
special attribute must not appear in a selector to the left of a >
combinator.max-length
特殊属性不得出现在>
组合符左侧的选择器中。
min-length
This special attribute may become unsupported in the future. Prefer using the :contains()
pseudo-class with a regular expression where it is available.
这个特殊属性将来可能会不受支持。最好将:contains()
伪类与可用的正则表达式一起使用。
Specifies the minimum length for content of HTML element. If this parameter is set and the content length is less than preset value, a rule does not apply to the element.
指定 HTML 元素内容的最小长度。如果设置了该参数并且内容长度小于预设值,则规则不适用于该元素。
For example: 例如:
$$div[tag-content="banner"][min-length="400"]
This rule will remove all the div
elements, whose code contains the substring banner
and the length of which exceeds 400
characters.
该规则将删除所有代码中包含子字符串banner
且长度超过400
字符的div
元素。
The min-length
special attribute must not appear in a selector to the left of a >
combinator.min-length
特殊属性不得出现在>
组合符左侧的选择器中。
Pseudo-classes 伪类
:contains()
Syntax 句法
:contains(unquoted text)
or 或者
:contains(/reg(ular )?ex(pression)?/)
:-abp-contains()
and :has-text()
are synonyms for :contains()
.:-abp-contains()
和:has-text()
是:contains()
的同义词。
Requires that the inner HTML of the element contains the specified text or matches the specified regular expression.
要求元素的内部 HTML 包含指定的文本或与指定的正则表达式匹配。
A :contains()
pseudo-class must not appear in a selector to the left of a >
combinator.:contains()
伪类不得出现在>
组合器左侧的选择器中。
Exceptions 例外情况
Similar to hiding rules, there is a special type of rules that disable the selected HTML filtering rule for particular domains.
The syntax is the same, you just have to change $$
to $@$
.
与隐藏规则类似,有一种特殊类型的规则可以禁用特定域的选定 HTML 过滤规则。语法是相同的,只需将$$
更改为$@$
。
For example, there is a rule in filter:
例如filter中有一条规则:
$$script[tag-content="banner"]
If you want to disable it for example.com
, you can create an exception rule:
如果您想对example.com
禁用它,您可以创建一个例外规则:
example.com$@$script[tag-content="banner"]
Sometimes, it may be necessary to disable all restriction rules. For example, to conduct tests. To do this, use the exclusion rule without specifying a domain.
有时,可能需要禁用所有限制规则。例如,进行测试。为此,请使用排除规则而不指定域。
$@$script[tag-content="banner"]
We recommend to use this kind of exceptions only if it is not possible to change the hiding rule itself. In other cases it is better to change the original rule, using domain restrictions.
我们建议仅当无法更改隐藏规则本身时才使用此类例外。在其他情况下,最好使用域限制来更改原始规则。
JavaScript rules JavaScript 规则
AdGuard supports a special type of rules that allows you to inject any JavaScript code to websites pages.
AdGuard 支持一种特殊类型的规则,允许您将任何 JavaScript 代码注入网站页面。
We strongly recommend using scriptlets instead of JavaScript rules whenever possible. JS rules are supposed to help with debugging, but as a long-time solution a scriptlet rule should be used.
我们强烈建议尽可能使用scriptlet而不是 JavaScript 规则。 JS 规则应该有助于调试,但作为长期解决方案,应该使用 scriptlet 规则。
Syntax 句法
rule = [domains] "#%#" script
domains
— domain restriction for the rule. Same principles as in element hiding rules.domains
— 规则的域限制。与元素隐藏规则中的原理相同。script
— arbitrary JavaScript code in one string.script
—一个字符串中的任意 JavaScript 代码。
Examples 示例
example.org#%#window.__gaq = undefined;
executes the codewindow.__gaq = undefined;
on all pages atexample.org
and all subdomains.
example.org#%#window.__gaq = undefined;
执行代码window.__gaq = undefined;
在example.org
的所有页面和所有子域上。
Exceptions 例外情况
Similar to hiding rules, there is a special type of rules that disable the selected javascript rule for particular domains.
The syntax is the same, you just have to change #%#
to #@%#
.
与隐藏规则类似,有一种特殊类型的规则可以禁用特定域的所选 JavaScript 规则。语法是相同的,只需将#%#
更改为#@%#
即可。
For example, there is a rule in filter:
例如filter中有一条规则:
#%#window.__gaq = undefined;
If you want to disable it for example.com
, you can create an exception rule:
如果您想对example.com
禁用它,您可以创建一个例外规则:
example.com#@%#window.__gaq = undefined;
Sometimes, it may be necessary to disable all restriction rules. For example, to conduct tests. To do this, use the exclusion rule without specifying a domain.
有时,可能需要禁用所有限制规则。例如,进行测试。为此,请使用排除规则而不指定域。
#@%#window.__gaq = undefined;
We recommend to use this kind of exceptions only if it is not possible to change the hiding rule itself.
In other cases it is better to change the original rule, using domain restrictions.
我们建议仅当无法更改隐藏规则本身时才使用此类例外。在其他情况下,最好使用域限制来更改原始规则。
JavaScript rules can only be used in trusted filters.
JavaScript 规则只能在受信任的过滤器中使用。
JavaScript rules are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持 JavaScript 规则。
Scriptlet rules 小脚本规则
Scriptlet is a JavaScript function that provides extended capabilities for content blocking.
These functions can be used in a declarative manner in AdGuard filtering rules.
Scriptlet 是一个 JavaScript 函数,提供内容阻止的扩展功能。这些函数可以在 AdGuard 过滤规则中以声明方式使用。
AdGuard supports a lot of different scriptlets. In order to achieve cross-blocker compatibility, we also support syntax of uBO and ABP.
AdGuard 支持许多不同的 scriptlet。为了实现跨拦截器兼容性,我们还支持uBO和ABP语法。
Blocking rules syntax 阻止规则语法
[domains]#%#//scriptlet(name[, arguments])
domains
— optional, a list of domains where the rule should be applied;domains
— 可选,应应用规则的域列表;name
— required, a name of the scriptlet from AdGuard Scriptlets library;name
— 必需,来自 AdGuard Scriptlets 库的 scriptlet 的名称;arguments
— optional, a list ofstring
arguments (no other types of arguments are supported).arguments
— 可选,string
参数列表(不支持其他类型的参数)。
Examples 示例
Apply the
abort-on-property-read
scriptlet on all pages ofexample.org
and its subdomains, and pass it analert
argument:
在example.org
及其子域的所有页面上应用abort-on-property-read
脚本,并向其传递一个alert
参数:example.org#%#//scriptlet('abort-on-property-read', 'alert')
Remove the
branding
class from alldiv[class^="inner"]
elements on all pages ofexample.org
and its subdomains:
从example.org
及其子域的所有页面上的所有div[class^="inner"]
元素中删除branding
类:example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')
Exception rules syntax 异常规则语法
Exception rules can disable some scriptlets on particular domains. The syntax for exception scriptlet rules is similar to normal scriptlet rules but uses #@%#
instead of #%#
:
例外规则可以禁用特定域上的某些 scriptlet。异常 scriptlet 规则的语法与普通 scriptlet 规则类似,但使用#@%#
而不是#%#
:
[domains]#@%#//scriptlet([name[, arguments]])
domains
— optional, a list of domains where the rule should be applied;domains
— 可选,应应用规则的域列表;name
— optional, a name of the scriptlet to except from the applying; if not set, all scriptlets will not be applied;name
— 可选,要从应用程序中排除的 scriptlet 的名称;如果未设置,则不会应用所有 scriptlet;arguments
— optional, a list ofstring
arguments to match the same blocking rule and disable it.arguments
— 可选,string
参数列表,用于匹配相同的阻止规则并禁用它。
Examples 示例
Disable specific scriptlet rule so that only
abort-on-property-read
is applied only onexample.org
and its subdomains:
禁用特定的 scriptlet 规则,以便仅在example.org
及其子域上应用abort-on-property-read
:example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
example.com#@%#//scriptlet("abort-on-property-read", "alert")Disable all
abort-on-property-read
scriptlets forexample.com
and its subdomains:
禁用example.com
及其子域的所有abort-on-property-read
scriptlet:example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
example.com#@%#//scriptlet("abort-on-property-read")Disable all scriptlets for
example.com
and its subdomains:
禁用example.com
及其子域的所有 scriptlet:example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
example.com#@%#//scriptlet()Apply
set-constant
andset-cookie
to any web page, but due to special scriptlet exception rule only theset-constant
scriptlet will be applied onexample.org
and its subdomains:
将set-constant
和set-cookie
应用到任何网页,但由于特殊的 scriptlet 例外规则,只有set-constant
scriptlet 将应用于example.org
及其子域:#%#//scriptlet('set-constant', 'adList', 'emptyArr')
#%#//scriptlet('set-cookie', 'accepted', 'true')
example.org#@%#//scriptlet('set-cookie')Apply
adjust-setInterval
to any web page andset-local-storage-item
onexample.com
and its subdomains, but there are also multiple scriptlet exception rules, so no scriptlet rules will be applied onexample.com
and its subdomains:
将adjust-setInterval
应用于任何网页,并在example.com
及其子域上set-local-storage-item
,但也有多个 scriptlet 例外规则,因此不会在example.com
及其子域上应用 scriptlet 规则:#%#//scriptlet('adjust-setInterval', 'count', '*', '0.001')
example.com#%#//scriptlet('set-local-storage-item', 'ALLOW_COOKIES', 'false')
example.com#@%#//scriptlet()
Learn more about how to debug scriptlets.
了解有关如何调试 scriptlet 的更多信息。
More information about scriptlets can be found on GitHub.
有关 scriptlet 的更多信息可以在 GitHub 上找到。
Scriptlet rules are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持 Scriptlet 规则。
The full syntax of scriptlet exception rules is supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.16 or later, and AdGuard Browser Extension for Chrome, Firefox, and Edge with TSUrlFilter v3.0 or later. Previous versions only support exception rules that disable specific scriptlets.
使用CoreLibs v1.16 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android,以及使用TSUrlFilter v3.0 或更高版本的适用于 Chrome、Firefox 和 Edge 的 AdGuard 浏览器扩展支持 scriptlet 例外规则的完整语法。以前的版本仅支持禁用特定 scriptlet 的异常规则。
Trusted scriptlets 可信脚本
Trusted scriptlets are scriptlets with extended functionality. It means the same syntax and restrictions. Trusted scriptlet names are prefixed with trusted-
, e.g. trusted-set-cookie
, to be easily distinguished from common scriptlets.
受信任的 scriptlet 是具有扩展功能的scriptlet 。这意味着相同的语法和限制。受信任的 scriptlet 名称以trusted-
为前缀,例如trusted-set-cookie
,以便于与常见的 scriptlet 轻松区分。
Trusted scriptlets are not compatible with other ad blockers except AdGuard.
受信任的 scriptlet 与除 AdGuard 之外的其他广告拦截器不兼容。
Trusted scriptlets rules can only be used in trusted filters.
受信任的 scriptlet 规则只能在受信任的过滤器中使用。
Trusted scriptlets rules are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持受信任的 scriptlet 规则。
Learn more about how to debug scriptlets.
了解有关如何调试 scriptlet 的更多信息。
More information about trusted scriptlets can be found on GitHub.
有关可信 scriptlet 的更多信息可以在 GitHub 上找到。
Modifiers for non-basic type of rules
非基本类型规则的修饰符
Each rule can be modified using the modifiers described in the following paragraphs.
每个规则都可以使用以下段落中描述的修饰符进行修改。
Syntax {#non-basic-rules-modifiers-syntax}
语法{#non-basic-rules-modifiers-syntax}
rule = "[$" modifiers "]" [rule text]
modifiers = modifier0[, modifier1[, ...[, modifierN]]]
modifier
— set of the modifiers described below.modifier
— 如下所述的修饰符集。rule text
— a rule to be modified.rule text
— 要修改的规则。
For example, [$domain=example.com,app=test_app]##selector
. 例如, [$domain=example.com,app=test_app]##selector
。
In the modifiers values, the following characters must be escaped: [
, ]
, ,
, and \
(unless
it is used for the escaping). Use \
to escape them. For example, an escaped bracket looks like
this: \]
.
在修饰符值中,必须对以下字符进行转义: [
、 ]
、 ,
和\
(除非用于转义)。使用\
来转义它们。例如,转义括号如下所示: \]
。
- ✅ — fully supported ✅ — 完全支持
- ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
✅ * — 支持,但可靠性可能会有所不同或可能会出现限制;检查修改器描述以获取更多详细信息 - ❌ — not supported ❌ — 不支持
$app
$app
modifier lets you narrow the rule coverage down to a specific application or a list of applications.
The modifier's behavior and syntax perfectly match the corresponding basic rules $app
modifier.$app
修饰符可让您将规则覆盖范围缩小到特定应用程序或应用程序列表。修饰符的行为和语法与相应的基本规则$app
修饰符完全匹配。
Examples 示例
[$app=org.example.app]example.com##.textad
hides adiv
with the classtextad
atexample.com
and all subdomains in requests sent from theorg.example.app
Android app.
[$app=org.example.app]example.com##.textad
隐藏example.com
中类为textad
div
以及从org.example.app
Android 应用发送的请求中的所有子域。[$app=~org.example.app1|~org.example.app2]example.com##.textad
hides adiv
with the classtextad
atexample.com
and all subdomains in requests sent from any app exceptorg.example.app1
andorg.example.app2
.
[$app=~org.example.app1|~org.example.app2]example.com##.textad
隐藏example.com
中类为textad
div
以及从除org.example.app1
和org.example.app2
之外的任何应用程序发送的请求中的所有子域。[$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300')
applies scriptletprevent-setInterval
only in Safari browser on Mac.
[$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300')
仅在 Mac 上的 Safari 浏览器中应用 scriptletprevent-setInterval
。[$app=org.example.app]#@#.textad
disables all##.textad
rules for all domains while usingorg.example.app
.
[$app=org.example.app]#@#.textad
使用org.example.app
时禁用所有域的所有##.textad
规则。
Such rules with $app
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android.
AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持此类带有$app
修饰符的规则。
$domain
$domain
modifier limits the rule application area to a list of domains and their subdomains.
The modifier's behavior and syntax perfectly match the corresponding basic rules $domain
modifier.$domain
修饰符将规则应用范围限制为域及其子域的列表。修饰符的行为和语法完全符合相应的基本规则$domain
modifier 。
Examples 示例
[$domain=example.com]##.textad
— hides adiv
with the classtextad
atexample.com
and all subdomains.
[$domain=example.com]##.textad
— 在example.com
和所有子域中隐藏带有类textad
的div
。[$domain=example.com|example.org]###adblock
— hides an element with attributeid
equalsadblock
atexample.com
,example.org
and all subdomains.
[$domain=example.com|example.org]###adblock
— 在example.com
、example.org
和所有子域中隐藏属性id
等于adblock
元素。[$domain=~example.com]##.textad
— this rule hidesdiv
elements of the classtextad
for all domains, exceptexample.com
and its subdomains.
[$domain=~example.com]##.textad
— 此规则隐藏所有域的textad
类的div
元素,但example.com
及其子域除外。
There are 2 ways to specify domain restrictions for non-basic rules:
有两种方法可以指定非基本规则的域限制:
- the "classic" way is to specify domains before rule mask and attributes:
example.com##.textad
;
“经典”方法是在规则掩码和属性之前指定域:example.com##.textad
; - the modifier approach is to specify domains via
$domain
modifier:[$domain=example.com]##.textad
.
修饰符方法是通过$domain
修饰符指定域:[$domain=example.com]##.textad
。
But rules with mixed style domains restriction are considered invalid. So, for example, the rule
[$domain=example.org]example.com##.textad
will be ignored.
但具有混合样式域限制的规则被视为无效。因此,例如,规则
[$domain=example.org]example.com##.textad
将被忽略。
Non-basic $domain
modifier limitations
非基本$domain
修饰符限制
Since the non-basic $domain
works the same as the basic one,
it has the same limitations.
由于非基本$domain
工作方式与基本 $domain 相同,因此它具有相同的限制。
Such rules with $domain
modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android,
AdGuard Browser Extension for Chrome, for Chrome MV3, Firefox, and Edge.
AdGuard for Windows、AdGuard for Mac、AdGuard for Android、AdGuard Chrome 浏览器扩展、Chrome MV3、Firefox 和 Edge 支持此类带有$domain
修饰符的规则。
$path
$path
modifier limits the rule application area to specific locations or pages on websites.$path
修饰符将规则应用区域限制为网站上的特定位置或页面。
Syntax 句法
$path ["=" pattern]
pattern
— optional, a path mask to which the rule is restricted. Its syntax and behavior are pretty much the same as with the pattern for basic rules. You can also use special characters, except for ||
, which does not make any sense in this case (see examples below).pattern
— 可选,规则所限制的路径掩码。它的语法和行为与基本规则的模式几乎相同。您还可以使用除||
之外的特殊字符,在这种情况下没有任何意义(参见下面的示例)。
If pattern
is not set for $path
, rule will apply only on the main page of website.
如果$path
没有设置pattern
,则规则仅适用于网站主页。
$path
modifier matches the query string as well.$path
修饰符也匹配查询字符串。
$path
modifier supports regular expressions in the same way basic rules do.$path
修饰符以与基本规则相同的方式支持正则表达式。
Examples 示例
[$path=page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
or/sub/page.html
or/another_page.html
[$path=page.html]##.textad
在/page.html
或/page.html?<query>
或/sub/page.html
或/another_page.html
处隐藏带有类textad
的div
[$path=/page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
or/sub/page.html
of any domain but not at/another_page.html
[$path=/page.html]##.textad
在任何域的/page.html
或/page.html?<query>
或/sub/page.html
处隐藏类textad
的div
,但不在/another_page.html
处/another_page.html
[$path=|/page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
of any domain but not at/sub/page.html
[$path=|/page.html]##.textad
在任何域的/page.html
或/page.html?<query>
处隐藏类textad
div
,但不在/sub/page.html
处[$path=/page.html|]##.textad
hides adiv
with the classtextad
at/page.html
or/sub/page.html
of any domain but not at/page.html?<query>
[$path=/page.html|]##.textad
在任何域的/page.html
或/sub/page.html
处隐藏带有类textad
div
,但不在/page.html?<query>
处?<query>[$path=/page*.html]example.com##.textad
hides adiv
with the classtextad
at/page1.html
or/page2.html
or any other path matching/page<...>.html
ofexample.com
[$path=/page*.html]example.com##.textad
在/page1.html
或/page2.html
或与example.com
的/page<...>.html
匹配的任何其他路径中隐藏带有类textad
div
[$path]example.com##.textad
hides adiv
with the classtextad
at the main page ofexample.com
[$path]example.com##.textad
在example.com
的主页上隐藏了一个带有textad
类的div
[$domain=example.com,path=/page.html]##.textad
hides adiv
with the classtextad
atpage.html
ofexample.com
and all subdomains but not atanother_page.html
[$domain=example.com,path=/page.html]##.textad
在example.com
和所有子域的page.html
处隐藏带有类textad
div
,但不在another_page.html
处隐藏[$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad
hides adiv
with the classtextad
at both/sub1/page.html
and/sub2/page.html
of any domain (please note the escaped special characters)
[$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad
在任何域的/sub1/page.html
和/sub2/page.html
处隐藏带有类textad
的div
(请注意转义的特殊字符)
Rules with $path
modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有$path
修饰符的规则。
$url
$url
modifier limits the rule application area to URLs matching the specified mask.$url
修饰符将规则应用区域限制为与指定掩码匹配的 URL。
Syntax 句法
url = pattern
where pattern
is pretty much the same as pattern
of the basic rules assuming that some characters must be escaped.
The special characters and regular expressions are supported as well.
其中pattern
与基本规则的pattern
几乎相同,假设某些字符必须转义。还支持特殊字符和正则表达式。
Examples 示例
[$url=||example.com/content/*]##div.textad
hides adiv
with the classtextad
at addresses likehttps://example.com/content/article.html
and evenhttps://subdomain.example.com/content/article.html
.
[$url=||example.com/content/*]##div.textad
隐藏一个带有类textad
的div
,地址如下https://example.com/content/article.html
甚至https://subdomain.example.com/content/article.html
。[$url=||example.org^]###adblock
hides an element with attributeid
equal toadblock
atexample.org
and its subdomains.
[$url=||example.org^]###adblock
在example.org
及其子域中隐藏属性id
等于adblock
的元素。[$url=/\[a-z\]+\\.example\\.com^/]##.textad
hidesdiv
elements of the classtextad
for all domains matching the regular expression[a-z]+\.example\.com^
.
[$url=/\[a-z\]+\\.example\\.com^/]##.textad
隐藏与正则表达式[az]+\.example\.com^
匹配的所有域的textad
类的div
元素。
$url
modifier limitations
$url
修饰符限制
In AdGuard Browser Extension, non-basic $url
modifier is not compatible with domain-specific rules
and other non-basic modifiers — $domain
and $path
.
For example, the rule [$url=/category/*]example.com###textad
will not be applied.
在 AdGuard 浏览器扩展中,非基本$url
修饰符与特定于域的规则和其他非基本修饰符 - $domain
和$path
不兼容。例如,规则 [$url=/category/*]example.com###textad
将不会被应用。
Rules with the $url
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later,
and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
使用CoreLibs v1.11 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 以及带有TSUrlFilter v3.0.0 或更高版本的 AdGuard 浏览器扩展支持带有$url
修饰符的规则。
Information for filter maintainers
过滤器维护人员的信息
If you maintain a third-party filter that is known to AdGuard, you might be interested in the information presented in this section. Please note that hints will be applied to registered filters only.
如果您维护 AdGuard 已知的第三方过滤器,您可能会对本节中提供的信息感兴趣。请注意,提示将仅应用于已注册的过滤器。
The filter is considered to be registered and known by AdGuard, if it is present in the known filters index. If you want your filter to be registered, please file an issue to AdguardFilters repo.
如果该过滤器存在于已知过滤器索引中,则该过滤器被认为已被 AdGuard 注册并已知。如果您希望注册您的过滤器,请向AdguardFilters repo提交问题。
Preprocessor directives 预处理器指令
We provide preprocessor directives that can be used by filter maintainers to improve compatibility with different ad blockers and provide:
我们提供预处理器指令,过滤器维护人员可以使用这些指令来提高与不同广告拦截器的兼容性,并提供:
- including a file 包括一个文件
- applying rules conditionally by ad blocker type
按广告拦截器类型有条件地应用规则 - content blocker specifying for rules applying in Safari
为 Safari 中应用的规则指定内容拦截器
Any mistake in a preprocessor directive will lead to AdGuard failing the filter update in the same way as if the filter URL was unavailable.
预处理器指令中的任何错误都会导致 AdGuard 过滤器更新失败,就像过滤器 URL 不可用一样。
Preprocessor directives can be used in the user rules or in the custom filters.
预处理器指令可以在用户规则或自定义过滤器中使用。
Including a file 包括一个文件
The !#include
directive allows to include contents of a specified file into the filter. It supports only files from the same origin to make sure that the filter maintainer is in control of the specified file. The included file can also contain pre-directives (even other !#include
directives). Ad blockers should consider the case of recursive !#include
and implement a protection mechanism.!#include
指令允许将指定文件的内容包含到过滤器中。它仅支持来自相同来源的文件,以确保过滤器维护者控制指定的文件。包含的文件还可以包含前置指令(甚至其他!#include
指令)。广告拦截器应考虑递归!#include
的情况并实施保护机制。
Syntax 句法
!#include file_path
where file_path
is a same origin absolute or relative file path to be included.
其中file_path
是要包含的同源绝对或相对文件路径。
The files must originate from the same domain, but may be located in a different folder.
这些文件必须来自同一域,但可以位于不同的文件夹中。
If included file is not found or unavailable, the whole filter update should fail.
如果包含的文件未找到或不可用,则整个过滤器更新将失败。
Same-origin limitation should be disabled for local custom filters.
对于本地自定义过滤器,应禁用同源限制。
Examples 示例
Filter URL: https://example.org/path/filter.txt
过滤网址: https://example.org/path/filter.txt
! Valid (same origin):
!#include https://example.org/path/includedfile.txt
!
! Valid (relative path):
!#include /includedfile.txt
!#include ../path2/includedfile.txt
!
! Invalid (another origin):
!#include https://domain.com/path/includedfile.txt
Conditions 状况
Filter maintainers can use conditions to supply different rules depending on the ad blocker type.
A conditional directive beginning with an !#if
directive must explicitly be terminated with an !#endif
directive.
Conditions support all basic logical operators.
过滤器维护者可以根据广告拦截器类型使用条件来提供不同的规则。以!#if
指令开头的条件指令必须显式地以!#endif
指令终止。条件支持所有基本逻辑运算符。
There are two possible scenarios:
有两种可能的情况:
When an ad blocker encounters an
!#if
directive and no!#else
directive, it will compile the code between!#if
and!#endif
directives only if the specified condition is true.
当广告拦截器遇到!#if
指令且没有!#else
指令时,仅当指定条件为 true 时,它才会编译!#if
和!#endif
指令之间的代码。If there is an
!#else
directive, the code between!#if
and!#else
will be compiled if the condition is true; otherwise, the code between!#else
and!#endif
will be compiled.
如果存在!#else
指令,则如果条件为 true,则将编译!#if
和!#else
之间的代码;否则,!#else
和!#endif
之间的代码将被编译。
Whitespaces matter. !#if
is a valid directive, while !# if
is not.
空格很重要。 !#if
是有效指令,而!# if
则不是。
Syntax 句法
!#if (conditions)
rules_list
!#endif
or 或者
!#if (conditions)
true_conditions_rules_list
!#else
false_conditions_rules_list
!#endif
where: 在哪里:
!#if (conditions)
— start of the block when conditions are true!#if (conditions)
— 条件为真时块的开始conditions
— just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. Authors of ad blockers define on their own what exact constants they declare. Possible values:conditions
- 就像在一些流行的编程语言中一样,预处理器条件基于广告拦截器声明的常量。广告拦截器的作者自行定义了他们声明的确切常量。可能的值:adguard
always declared; shows maintainers that this is one of AdGuard products; should be enough in 95% of casesadguard
始终声明;向维护者展示这是 AdGuard 产品之一;在 95% 的情况下应该足够了- product-specific constants for cases when you need a rule to work (or not work — then
!
should be used before constant) in a specific product only:
当您需要规则在特定产品中起作用(或不起作用 - 那么!
应该在常量之前使用)时,产品特定的常量:adguard_app_windows
— AdGuard for Windowsadguard_app_windows
— AdGuard Windows 版adguard_app_mac
— AdGuard for Macadguard_app_mac
— Mac 版 AdGuardadguard_app_android
— AdGuard for Androidadguard_app_android
— 适用于 Android 的 AdGuardadguard_app_ios
— AdGuard for iOSadguard_app_ios
— 适用于 iOS 的 AdGuardadguard_ext_safari
— AdGuard for Safariadguard_ext_safari
— Safari 的 AdGuardadguard_ext_chromium
— AdGuard Browser Extension for Chrome (and chromium-based browsers, e.g. new Microsoft Edge)adguard_ext_chromium
— 适用于 Chrome 的 AdGuard 浏览器扩展(以及基于 chromium 的浏览器,例如新的 Microsoft Edge)adguard_ext_chromium_mv3
— AdGuard for Chrome MV3adguard_ext_chromium_mv3
— Chrome MV3 的 AdGuardadguard_ext_firefox
— AdGuard Browser Extension for Firefoxadguard_ext_firefox
— 适用于 Firefox 的 AdGuard 浏览器扩展adguard_ext_edge
— AdGuard Browser Extension for Edge Legacyadguard_ext_edge
— 适用于 Edge Legacy 的 AdGuard 浏览器扩展adguard_ext_opera
— AdGuard Browser Extension for Operaadguard_ext_opera
— 用于 Opera 的 AdGuard 浏览器扩展adguard_ext_android_cb
— AdGuard Content Blocker for mobile Samsung and Yandex browsersadguard_ext_android_cb
— 适用于移动 Samsung 和 Yandex 浏览器的 AdGuard 内容拦截器ext_ublock
— special case; this one is declared when a uBlock version of a filter is compiled by the FiltersRegistryext_ublock
— 特殊情况;当FiltersRegistry编译过滤器的 uBlock 版本时声明此一个cap_html_filtering
— products that support HTML filtering rules: AdGuard for Windows, AdGuard for Mac, and AdGuard for Androidcap_html_filtering
— 支持 HTML 过滤规则的产品:AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android
!#else
— start of the block when conditions are false!#else
— 当条件为 false 时块的开始rules_list
,true_conditions_rules_list
,false_conditions_rules_list
— lists of rulesrules_list
,true_conditions_rules_list
,false_conditions_rules_list
— 规则列表!#endif
— end of the block!#endif
— 块结束
Examples 示例
! for all AdGuard products except AdGuard for Safari
!#if (adguard && !adguard_ext_safari)
||example.org^$third-party
domain.com##div.ad
!#endif
! directives even can be combined
!#if (adguard_app_android)
!#include /androidspecific.txt
!#endif
!#if (adguard && !adguard_ext_safari)
! for all AdGuard products except AdGuard for Safari
||example.org^$third-party
domain.com##div.ad
!#else
! for AdGuard for Safari only
||subdomain.example.org^$third-party
!#endif
The !#else
directive is supported by the FiltersDownloader v1.1.20 or later.
FiltersDownloader v1.1.20 或更高版本支持!#else
指令。
It is already supported for filter lists compiled by the FiltersRegistry,
but it still may not be supported by AdGuard products when adding a filter list with !#else
as a custom one.
The following products will support it in the mentioned versions or later:
FiltersRegistry编译的过滤器列表已经支持它,但在添加带有!#else
过滤器列表作为自定义列表时,AdGuard 产品可能仍然不支持它。以下产品将在上述版本或更高版本中支持它:
Safari affinity Safari 亲和力
Safari's limit for each content blocker is 150,000 active rules. But in AdGuard for Safari and AdGuard for iOS, we've split the rules into 6 content blockers, thus increasing the rule limit to 900,000.
Safari 对每个内容拦截器的限制是 150,000 个活动规则。但在 AdGuard for Safari 和 AdGuard for iOS 中,我们将规则分为 6 个内容拦截器,从而将规则限制增加到 900,000 个。
Here is the composition of each content blocker:
以下是每个内容拦截器的组成:
- AdGuard General — Ad Blocking, Language-specific
AdGuard General — 广告拦截,特定语言 - AdGuard Privacy — Privacy
AdGuard 隐私 — 隐私 - AdGuard Social — Social Widgets, Annoyances
AdGuard Social — 社交小部件、烦恼 - AdGuard Security — Security
AdGuard 安全 — 安全 - AdGuard Other — Other AdGuard 其他 — 其他
- AdGuard Custom — Custom AdGuard 自定义 — 自定义
User rules and allowlist are added to every content blocker.
用户规则和许可名单已添加到每个内容拦截器中。
The main disadvantage of using multiple content blockers is that rules from different blockers are applied independently.
使用多个内容拦截器的主要缺点是不同拦截器的规则是独立应用的。
Blocking rules are not affected by this, but unblocking rules may cause problems. If a blocking rule is in one content blocker and an exception is in another, the exception will not work. Filter maintainers use !#safari_cb_affinity
to define Safari content blocker affinity for the rules inside of the directive block.
阻止规则不受此影响,但解除阻止规则可能会导致问题。如果阻止规则位于一个内容阻止程序中,而例外情况位于另一内容阻止程序中,则该例外将不起作用。过滤器维护者使用!#safari_cb_affinity
为指令块内的规则定义 Safari 内容拦截器亲和力。
Syntax 句法
!#safari_cb_affinity(content_blockers)
rules_list
!#safari_cb_affinity
where: 在哪里:
!#safari_cb_affinity(content_blockers)
— start of the block
!#safari_cb_affinity(content_blockers)
— 块的开始content_blockers
— comma-separated list of content blockers. Possible values:content_blockers
— 以逗号分隔的内容拦截器列表。可能的值:general
— AdGuard General content blockergeneral
— AdGuard 通用内容拦截器privacy
— AdGuard Privacy content blockerprivacy
— AdGuard 隐私内容拦截器social
— AdGuard Social content blockersocial
— AdGuard 社交内容拦截器security
— AdGuard Security content blockersecurity
— AdGuard 安全内容拦截器other
— AdGuard Other content blockerother
— AdGuard 其他内容拦截器custom
— AdGuard Custom content blockercustom
— AdGuard 自定义内容拦截器all
— special keyword that means that the rules must be included into all content blockersall
— 特殊关键字,意味着规则必须包含在所有内容拦截器中
rules_list
— list of rulesrules_list
— 规则列表!#safari_cb_affinity
— end of the block!#safari_cb_affinity
— 块的末尾
Examples 示例
! to unhide specific element which is hidden by AdGuard Base filter:
!#safari_cb_affinity(general)
example.org#@#.adBanner
!#safari_cb_affinity
! to allowlist basic rule from AdGuard Tracking Protection filter:
!#safari_cb_affinity(privacy)
@@||example.org^
!#safari_cb_affinity
Hints 提示
"Hint" is a special comment, instruction to the filters compiler used on the server side (see FiltersRegistry).
“提示”是一个特殊的注释,是对服务器端使用的过滤器编译器的指令(请参阅FiltersRegistry )。
Syntax 句法
!+ HINT_NAME1(PARAMS) HINT_NAME2(PARAMS)
Multiple hints can be applied.
可以应用多个提示。
NOT_OPTIMIZED
hint
NOT_OPTIMIZED
提示
For each filter, AdGuard compiles two versions: full and optimized. Optimized version is much more lightweight and does not contain rules which are not used at all or used rarely.
对于每个过滤器,AdGuard 编译两个版本:完整版本和优化版本。优化版本更加轻量级,并且不包含根本不使用或很少使用的规则。
Rules usage frequency comes from the collected filter rules statistics. But filters optimization is based on more than that — some filters have specific configuration. This is how it looks like for Base filter:
规则使用频率来自收集的过滤规则统计数据。但过滤器优化不仅仅基于此——一些过滤器具有特定的配置。这是基本过滤器的样子:
"filter": AdGuard Base filter,
"percent": 30,
"minPercent": 20,
"maxPercent": 40,
"strict": true
where: 在哪里:
- filter — filter identifier
filter — 过滤器标识符 - percent — expected optimization percent
~= (rules count in optimized filter) / (rules count in original filter) * 100
百分比— 预期优化百分比~= (rules count in optimized filter) / (rules count in original filter) * 100
- minPercent — lower bound of
percent
value
minPercent —percent
值的下限 - maxPercent — upper bound of
percent
value
maxPercent —percent
值的上限 - strict — if
percent < minPercent
ORpercent > maxPercent
and strict mode is on then filter compilation should fail, otherwise original rules must be used
strict — 如果percent < minPercent
或percent > maxPercent
且严格模式处于开启状态,则过滤器编译应失败,否则必须使用原始规则
In other words, percent
is the "compression level". For instance, for the Base filter it is configured to 40%. It means that optimization algorithm should strip 60% of rules.
换句话说, percent
是“压缩级别”。例如,对于基本过滤器,其配置为 40%。这意味着优化算法应该剥离 60% 的规则。
Eventually, here are the two versions of the Base filter for AdGuard Browser Extension:
最终,以下是 AdGuard 浏览器扩展的基本过滤器的两个版本:
- full: https://filters.adtidy.org/extension/chromium/filters/2.txt
完整: https://filters.adtidy.org/extension/chromium/filters/2.txt - optimized: https://filters.adtidy.org/extension/chromium/filters/2_optimized.txt
优化: https ://filters.adtidy.org/extension/chromium/filters/2_optimized.txt
If you want to add a rule which should not be removed at optimization use the NOT_OPTIMIZED
hint:
如果要添加优化时不应删除的规则,请使用NOT_OPTIMIZED
提示:
!+ NOT_OPTIMIZED
||example.org^
And this rule will not be optimized only for AdGuard for Android:
并且此规则不会仅针对 Android 版 AdGuard 进行优化:
!+ NOT_OPTIMIZED PLATFORM(android)
||example.org^
PLATFORM
and NOT_PLATFORM
hints
PLATFORM
和NOT_PLATFORM
提示
Used to specify the platforms to apply the rules. List of existing platforms and links to Base filter, for example, for each of them:
用于指定应用规则的平台。现有平台的列表以及基本过滤器的链接,例如,每个平台:
windows
— AdGuard for Windows — https://filters.adtidy.org/windows/filters/2.txtmac
— AdGuard for Mac — https://filters.adtidy.org/mac_v2/filters/2.txtandroid
— AdGuard for Android — https://filters.adtidy.org/android/filters/2.txtios
— AdGuard for iOS — https://filters.adtidy.org/ios/filters/2.txtext_chromium
— AdGuard Browser Extension for Chrome — https://filters.adtidy.org/extension/chromium/filters/2.txtext_chromium
— 适用于 Chrome 的 AdGuard 浏览器扩展 — https://filters.adtidy.org/extension/chromium/filters/2.txtext_chromium_mv3
— AdGuard Browser Extension for Chrome MV3 — https://filters.adtidy.org/extension/chromium-mv3/filters/2.txtext_chromium_mv3
— 适用于 Chrome MV3 的 AdGuard 浏览器扩展 — https://filters.adtidy.org/extension/chromium-mv3/filters/2.txtext_ff
— AdGuard Browser Extension for Firefox — https://filters.adtidy.org/extension/firefox/filters/2.txtext_ff
— 适用于 Firefox 的 AdGuard 浏览器扩展 — https://filters.adtidy.org/extension/firefox/filters/2.txtext_edge
— AdGuard Browser Extension for Edge — https://filters.adtidy.org/extension/edge/filters/2.txtext_edge
— 适用于 Edge 的 AdGuard 浏览器扩展 — https://filters.adtidy.org/extension/edge/filters/2.txtext_opera
— AdGuard Browser Extension for Opera — https://filters.adtidy.org/extension/opera/filters/2.txtext_opera
— 适用于 Opera 的 AdGuard 浏览器扩展 — https://filters.adtidy.org/extension/opera/filters/2.txtext_safari
— AdGuard for Safari — https://filters.adtidy.org/extension/safari/filters/2.txtext_android_cb
— AdGuard Content Blocker — https://filters.adtidy.org/extension/android-content-blocker/filters/2.txtext_android_cb
— AdGuard 内容拦截器 — https://filters.adtidy.org/extension/android-content-blocker/filters/2.txtext_ublock
— uBlock Origin — https://filters.adtidy.org/extension/ublock/filters/2.txtext_ublock
— uBlock 起源 — https://filters.adtidy.org/extension/ublock/filters/2.txt
Examples 示例
This rule will be available only in AdGuard for Windows, Mac, Android:
此规则仅适用于 Windows、Mac、Android 版 AdGuard:
!+ PLATFORM(windows,mac,android)
||example.org^
Except for AdGuard for Safari, AdGuard Content Blocker, and AdGuard for iOS, this rule is available on all platforms:
除了 AdGuard for Safari、AdGuard Content Blocker 和 AdGuard for iOS 之外,此规则适用于所有平台:
!+ NOT_PLATFORM(ext_safari, ext_android_cb, ios)
||example.org^
How to debug filtering rules
如何调试过滤规则
It may be possible to create simple filtering rules "in your head" but for anything even slightly more complicated you will need additional tools to debug and iterate them. There are tools to assist you with that.
也许可以“在头脑中”创建简单的过滤规则,但对于稍微复杂一点的规则,您将需要额外的工具来调试和迭代它们。有一些工具可以帮助您做到这一点。
You can use DevTools in Chrome and its analogs in other browsers but most AdGuard products provide another one — Filtering log.
您可以在 Chrome 中使用 DevTools 及其在其他浏览器中的类似工具,但大多数 AdGuard 产品提供另一种工具 - 过滤日志。
Filtering log 过滤日志
Filtering log is an advanced tool that will be helpful mostly to filter developers. It lists all web requests that pass through AdGuard, gives you exhaustive information on each of them, offers multiple sorting options, and has other useful features.
过滤日志是一个高级工具,主要对过滤开发人员有帮助。它列出了通过 AdGuard 的所有 Web 请求,为您提供每个请求的详尽信息,提供多种排序选项,并具有其他有用的功能。
Depending on which AdGuard product you are using, Filtering log can be located in different places.
根据您使用的 AdGuard 产品,过滤日志可能位于不同的位置。
- In AdGuard for Windows, you can find it in the Ad Blocker tab or via the tray menu
在AdGuard for Windows中,您可以在“广告拦截器”选项卡中或通过托盘菜单找到它 - In AdGuard for Mac, it is located in Settings → Advanced → Filtering log
在AdGuard for Mac中,它位于“设置”→“高级”→“过滤日志” - In AdGuard for Android, you can find it under Statistics → Recent activity. Recent activity can also be accessed from the Assistant
在AdGuard for Android中,您可以在统计 → 最近活动下找到它。还可以通过助理访问最近的活动 - In AdGuard Browser Extension, it is accessible from the Miscellaneous settings tab or by right-clicking the extension icon. Only Chromium- and Firefox-based web browsers show applied element hiding rules (including CSS, ExtCSS) and JS rules and scriptlets in their Filtering logs
在AdGuard 浏览器扩展中,可以通过“其他设置”选项卡或右键单击扩展图标来访问它。仅基于 Chromium 和 Firefox 的 Web 浏览器在其过滤日志中显示应用的元素隐藏规则(包括 CSS、ExtCSS)以及JS 规则和 scriptlet
In AdGuard for iOS and AdGuard for Safari, Filtering log does not exist because of the way content blockers are implemented in Safari. AdGuard does not see the web requests and therefore cannot display them.
在AdGuard for iOS和AdGuard for Safari中,由于 Safari 中内容拦截器的实现方式,不存在过滤日志。 AdGuard 看不到网络请求,因此无法显示它们。
Selectors debugging mode 选择器调试模式
Sometimes, you might need to check the performance of a given selector or a stylesheet. In order to do it without interacting with JavaScript directly, you can use a special debug
style property. When ExtendedCss
meets this property, it enables the debugging mode either for a single selector or for all selectors, depending on the debug
value.
有时,您可能需要检查给定选择器或样式表的性能。为了在不直接与 JavaScript 交互的情况下完成此操作,您可以使用特殊的debug
样式属性。当ExtendedCss
满足此属性时,它会为单个选择器或所有选择器启用调试模式,具体取决于debug
值。
Open the browser console while on a web page to see the timing statistics for selector(s) that were applied there. Debugging mode displays the following stats as object where each of the debugged selectors are keys, and value is an object with such properties:
在网页上打开浏览器控制台可查看此处应用的选择器的计时统计信息。调试模式将以下统计信息显示为对象,其中每个调试的选择器都是键,值是具有此类属性的对象:
Always printed: 始终打印:
selectorParsed
— text of the parsed selector, may differ from the input oneselectorParsed
— 解析选择器的文本,可能与输入的不同timings
— list of DOM nodes matched by the selectortimings
— 选择器匹配的 DOM 节点列表appliesCount
— total number of times that the selector has been applied on the pageappliesCount
— 选择器在页面上应用的总次数appliesTimings
— time that it took to apply the selector on the page, for each of the instances that it has been applied (in milliseconds)appliesTimings
— 对于已应用的每个实例,在页面上应用选择器所花费的时间(以毫秒为单位)meanTiming
— mean time that it took to apply the selector on the pagemeanTiming
— 在页面上应用选择器所花费的平均时间standardDeviation
— standard deviationstandardDeviation
— 标准差timingsSum
— total time it took to apply the selector on the page across all instancestimingsSum
— 在所有实例的页面上应用选择器所花费的总时间
Printed only for remove pseudos:
仅打印用于删除伪项:
removed
— flag to signal if elements were removedremoved
— 标记以指示元素是否已被删除
Printed if elements are not removed:
如果元素未被删除则打印:
matchedElements
— list of DOM nodes matched by the selectormatchedElements
— 与选择器匹配的 DOM 节点列表styleApplied
— parsed rule style declaration related to the selectorstyleApplied
— 与选择器相关的解析规则样式声明
Examples 示例
Debugging a single selector:
调试单个选择器:
When the value of the debug
property is true
, only information about this selector will be shown in the browser console.
当debug
属性的值为true
时,浏览器控制台中将仅显示有关此选择器的信息。
#$?#.banner { display: none; debug: true; }
Enabling global debug: 启用全局调试:
When the value of the debug
property is global
, the console will display information about all extended CSS selectors that have matches on the current page, for all the rules from any of the enabled filters.
当debug
属性的值为global
时,控制台将显示有关当前页面上具有匹配项的所有扩展 CSS 选择器的信息,以及来自任何已启用过滤器的所有规则。
#$?#.banner { display: none; debug: global; }
Testing extended selectors without AdGuard
在没有 AdGuard 的情况下测试扩展选择器
ExtendedCss can be executed on any page without using any AdGuard product. In order to do that you should copy and execute the following code in a browser console:
ExtendedCss可以在任何页面上执行,无需使用任何AdGuard产品。为此,您应该在浏览器控制台中复制并执行以下代码:
!function(e,t,d){C=e.createElement(t),C.src=d,C.onload=function(){alert("ExtendedCss loaded successfully")},s=e.getElementsByTagName(t)[0],s?s.parentNode.insertBefore(C,s):(h=e.getElementsByTagName("head")[0],h.appendChild(C))}(document,"script","https://AdguardTeam.github.io/ExtendedCss/extended-css.min.js");
Alternatively, install the ExtendedCssDebugger userscript.
或者,安装ExtendedCssDebugger 用户脚本。
Now you can now use the ExtendedCss
from global scope, and run its method query()
as Document.querySelectorAll()
.
现在,您可以在全局范围内使用ExtendedCss
,并将其方法query()
作为Document.querySelectorAll()
运行。
Examples 示例
const selector = 'div.block:has=(.header:matches-css(after, content: Ads))';
// array of HTMLElements matched the `selector` is to be returned
ExtendedCss.query(selector);
Debugging scriptlets 调试脚本
If you are using AdGuard Browser Extension and want to debug a scriptlet or a trusted scriptlet rule, you can get additional information by opening the Filtering log. In that case, scriptlets will switch to debug mode and there will be more information in the browser console.
如果您使用 AdGuard 浏览器扩展并想要调试scriptlet或受信任的 scriptlet规则,则可以通过打开过滤日志来获取其他信息。在这种情况下,scriptlet 将切换到调试模式,并且浏览器控制台中将显示更多信息。
The following scriptlets are especially developed for debug purposes:
以下 scriptlet 是专门为调试目的而开发的:
debug-current-inline-script
debug-on-property-read
debug-on-property-write
log-addEventListener
log-on-stack-trace
log-eval
log
The following scriptlets also may be used for debug purposes:
以下 scriptlet 也可用于调试目的:
json-prune
prevent-fetch
prevent-requestAnimationFrame
prevent-setInterval
prevent-setTimeout
prevent-window-open
with specifiedreplacement
parameter
使用指定的replacement
参数prevent-window-open
prevent-xhr
trusted-replace-fetch-response
trusted-replace-xhr-response
Compatibility tables legend
兼容性表图例
Product shortcuts 产品快捷键
CoreLibs apps
— AdGuard for Windows, AdGuard for Mac, and AdGuard for AndroidCoreLibs apps
— AdGuard for Windows 、 AdGuard for Mac和AdGuard for AndroidAdGuard for Chromium
— AdGuard Browser Extension for Chrome and other Chromium-based browsers such as Microsoft Edge, OperaAdGuard for Chromium
— 适用于 Chrome 和其他基于 Chromium 的浏览器(例如 Microsoft Edge、Opera)的 AdGuard 浏览器扩展AdGuard for Chrome MV3
— AdGuard Browser Extension for Chrome MV3AdGuard for Chrome MV3
—适用于 Chrome MV3 的 AdGuard 浏览器扩展AdGuard for Firefox
— AdGuard Browser Extension for FirefoxAdGuard for Firefox
— AdGuard Firefox 浏览器扩展AdGuard for iOS
— AdGuard for iOS and AdGuard Pro for iOS (for mobile Safari browser)AdGuard for iOS
— AdGuard for iOS和 AdGuard Pro for iOS(适用于移动 Safari 浏览器)AdGuard for Safari
— AdGuard for desktop Safari browserAdGuard for Safari
— AdGuard 适用于桌面 Safari 浏览器AdGuard Content Blocker
— Content Blocker for Android mobile browsers: Samsung Internet and Yandex BrowserAdGuard Content Blocker
— 适用于 Android 移动浏览器的内容拦截器:Samsung Internet 和 Yandex Browser
Compatibility shortcuts 兼容性快捷键
- ✅ — fully supported ✅ — 完全支持
- ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
✅ * — 支持,但可靠性可能会有所不同或可能会出现限制;检查修改器描述以获取更多详细信息 - 🧩 — may already be implemented in nightly or beta versions but is not yet supported in release versions
🧩 — 可能已经在 Nightly 或 Beta 版本中实现,但在发布版本中尚不支持 - ⏳ — feature that is planned to be implemented but is not yet available in any product
⏳ — 计划实现但尚未在任何产品中提供的功能 - ❌ — not supported ❌ — 不支持
- 👎 — deprecated; still supported but will be removed in the future
👎 — 已弃用;仍然受支持,但将来会被删除 - 🚫 — removed and no longer supported
🚫 — 已删除且不再受支持