这是用户在 2025-1-15 21:57 为 https://adguard.com/kb/general/ad-filtering/create-own-filters/ 保存的双语快照页面,由 沉浸式翻译 提供双语支持。了解如何保存?
Skip to main content  跳至主要内容

How to create your own ad filters
如何创建您自己的广告过滤器

info  信息

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 语法规范,但我们并不总是严格遵循此规范。

info  信息

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  通过域名屏蔽

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  阻止确切地址

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.
过滤规则支持多种修饰符,允许您微调规则行为。下面是带有一些简单修饰符的规则示例。

Basic rule modifiers

This rule blocks:  该规则阻止:

  • http://example.org/script.js if this script is loaded from example.com.
    http://example.org/script.js如果此脚本是从example.com加载的。

This rule does not block:
该规则不会阻止:

  • https://example.org/script.js if this script is loaded from example.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  解锁地址

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
解锁整个网站

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 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选择器#bannersMatches all elements with id attribute equal to banners.
匹配id属性等于banners的所有元素。

ID selector
Class selector  类选择器.bannersMatches all elements with class attribute containing banners.
匹配class属性包含banners的所有元素。

Class selector
Attribute selector  属性选择器div[class="banners"]Matches all div elements with class attribute exactly equal to banners.
匹配class属性完全等于banners的所有div元素。

Attribute selector
Attribute substring selector
属性子串选择器
div[class^="advert1"]Matches all div elements which class attribute starts with the advert1 string.
匹配class属性advert1字符串开头的所有div元素。

Attribute substring selector
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
Attribute substring selector
属性子串选择器
a[href^="http://example.com/"]Matches all links that are loaded from http://example.com/ domain.
匹配从http://example.com/域加载的所有链接。

Attribute substring selector
Attribute selector  属性选择器a[href="http://example.com/"]Matches all links to exactly the http://example.com/ address.
将所有链接与http://example.com/地址完全匹配。

Attribute selector

Restrictions and limitations
限制和限制

Trusted filters  值得信赖的过滤器

Some rules can be used only in trusted filters. This category includes:
某些规则只能在受信任的过滤器中使用。该类别包括:

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-partycontent-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.
此类规则的基本原理非常简单:您必须指定限制或扩展规则范围的地址和附加参数。

Sub-requests  子请求

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修饰符显式指定。

Response status  响应状态

Browser detects a blocked request as completed with an error.
浏览器检测到已阻止的请求已完成但有错误。

Rule length  规则长度

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 for http://*., 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 rule swf| corresponds to http://example.com/annoyingflash.swf , but not to http://example.com/swf/index.html. |http://example.org corresponds to http://example.org, but not to http://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
note  笔记

|, ||, ^ 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不正确,将被拦截器忽略。

Visual representation  视觉表现

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.
如果您希望在制定规则时更加灵活,可以使用正则表达式而不是带有特殊字符的默认简化掩码。

Performance  表现

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+/

Compatibility  兼容性

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.comsub.example.netexample.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.*

Compatibility  兼容性

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 like http://example.com/ads/banner.jpg and even http://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 to example.org and its subdomains.
    ||example.org^$third-party — 此规则阻止第三方对example.org及其子域的请求。

  • @@||example.com$document — general exception rule. It completely disables filtering for example.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  基本规则修改器

note  笔记

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 的 AdGuardAdGuard for Chrome MV3  适用于 Chrome 的 AdGuard MV3AdGuard for Firefox  适用于 Firefox 的 AdGuardAdGuard for iOS  iOS 版 AdGuardAdGuard for Safari  适用于 Safari 的 AdGuardAdGuard 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  $至
note  笔记
  • ✅ — 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 the org.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 both org.example.app1 and org.example.app2 apps.
    ||baddomain.com^$app=org.example.app1|org.example.app2 — 相同的规则,但它适用于org.example.app1org.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 the org.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 and org.example.app2.
    ||baddomain.com^$app=~org.example.app1|~org.example.app2 — 与上面相同,但现在排除了两个应用程序: org.example.app1org.example.app2
Restrictions  限制

Apps in the modifier value cannot have a wildcard, e.g. $app=com.*.music. Rules with such modifier are considered invalid.
修饰符值中的应用程序不能有通配符,例如$app=com.*.music 。具有此类修饰符的规则被视为无效。

Compatibility  兼容性
  • 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
Restrictions  限制
  • 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.
违反这些限制的规则被视为无效。

Compatibility  兼容性

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. for example.* it is co.uk in example.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 规则相同,但字符/$,|必须用\转义。
info  信息

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 domain example.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 both example.org and example.com.
    ||baddomain.com^$domain=example.org|example.com — 相同的规则,但它适用于example.orgexample.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 the example.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 both example.org and example.com.
    ||baddomain.com^$domain=example.org|example.com — 相同的规则,但它适用于example.orgexample.com
  • ||baddomain.com^$domain=~example.org blocks requests matching the pattern sent from any domain except example.org and its subdomains.
    ||baddomain.com^$domain=~example.org 阻止与除example.org及其子域之外的任何域发送的模式匹配的请求。
  • ||baddomain.com^$domain=example.org|~foo.example.org blocks requests sent from example.org and its subdomains, except the subdomain foo.example.org.
    ||baddomain.com^$domain=example.org|~foo.example.org 阻止从example.org及其子域(子域foo.example.org除外)发送的请求。
  • ||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/ blocks requests sent from example.org and example.com domains and all their subdomains.
    ||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/ 阻止从example.orgexample.com域及其所有子域发送的请求。
  • ||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/ blocks requests sent from any domains, except a.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.comb.co.uk等)的bc.comc.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修饰符不仅可以匹配引用域,还可以匹配目标域。当满足以下所有条件时会发生这种情况:

  1. The request has the document content type
    请求具有document内容类型
  2. The rule pattern does not match any particular domains
    规则模式不匹配任何特定域
  3. The rule pattern does not contain regular expressions
    规则模式不包含正则表达式
  4. 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 from example.org and example.com.
    *$cookie,domain=example.org|example.com 将阻止来自example.orgexample.com的所有请求的 cookie。
  • *$document,domain=example.org|example.com will block all requests to and from example.org and example.com.
    *$document,domain=example.org|example.com 将阻止所有发往和来自example.orgexample.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修饰符限制
Limitations  局限性

In AdGuard for Chrome MV3, regexp and any_tld_domain entries are not supported.
AdGuard for Chrome MV3中,不支持regexpany_tld_domain条目。

Restrictions  限制

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。

Compatibility  兼容性

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 the Set-Cookie header with the value matching foo literally.
    ||example.com^$header=set-cookie:foo 阻止其响应具有Set-Cookie标头且其值与字面匹配foo的请求。
  • ||example.com^$header=set-cookie blocks requests whose responses have the Set-Cookie header with any value.
    ||example.com^$header=set-cookie 阻止其响应具有任意值的Set-Cookie标头的请求。
  • @@||example.com^$header=set-cookie:/foo\, bar\$/ unblocks requests whose responses have the Set-Cookie header with value matching the foo, bar$ regular expression.
    @@||example.com^$header=set-cookie:/foo\, bar\$/ 取消阻止其响应具有Set-Cookie标头且其值与foo, bar$正则表达式匹配的请求。
  • @@||example.com^$header=set-cookie unblocks requests whose responses have a Set-Cookie header with any value.
    @@||example.com^$header=set-cookie 取消阻止其响应具有任意值的Set-Cookie标头的请求。
$header modifier limitations
$header修饰符限制
Restrictions  限制
  1. 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修饰符才能匹配。因此,如果请求在较早阶段被阻止或重定向,则无法应用修饰符。
  2. In Adguard Browser Extension, the $header modifier is only compatible with $csp, $removeheader, $important, and $badfilter.
    在 Adguard 浏览器扩展中, $header修饰符仅兼容 $csp$removeheader$important$badfilter
Compatibility  兼容性

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 block http://example.com/BannerAd.gif, but not http://example.com/bannerad.gif.
    */BannerAd.gif$match-case — 此规则将被阻止 http://example.com/BannerAd.gif ,但不是 http://example.com/bannerad.gif
Compatibility  兼容性

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 to evil.com.
    ||evil.com^$method=get|head仅阻止对evil.com GET 和 HEAD 请求。
  • ||evil.com^$method=~post|~put blocks any requests to evil.com except POST or PUT.
    ||evil.com^$method=~post|~put会阻止对evil.com的任何请求(POST 或 PUT 除外)。
  • @@||evil.com$method=get unblocks only GET requests to evil.com.
    @@||evil.com$method=get仅解除阻止对evil.com的 GET 请求。
  • @@||evil.com$method=~post unblocks any requests to evil.com except POST.
    @@||evil.com$method=~post取消阻止除 POST 之外的任何对evil.com的请求。
Restrictions  限制

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将被忽略。

Compatibility  兼容性

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 浏览器扩展支持。

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 to http://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/ ,则此规则将关闭必须打开指定站点的新选项卡。
Limitations  局限性
  1. The $popup modifier works best in AdGuard Browser Extension for Chromium-based browsers and Firefox.
    $popup修饰符在基于 Chromium 的浏览器和 Firefox 的 AdGuard 浏览器扩展中效果最佳。
  2. 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引擎中使用它们,并以编程方式关闭新选项卡。
  3. In AdGuard for iOS and AdGuard for Safari, $popup rules simply block the page right away.
    在 AdGuard for iOS 和 AdGuard for Safari 中, $popup规则只是立即阻止页面。
  4. 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 the document 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
Compatibility  兼容性

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 from domain.com to http://domain.com/icon.ico is a first-party request. A request from sub.domain.com to http://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.comhttp://domain.com/icon.ico的请求是第一方请求。从sub.domain.comhttp://domain.com/icon.ico的请求被视为第三方请求(而不是$~third-party修饰符)。
note  笔记

You can use a shorter name (alias) instead of using the full modifier name: $strict1p.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $strict1p

Compatibility  兼容性

Rules with the $strict-first-party modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.16 or later.
使用CoreLibs v1.16 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持带有$strict-first-party修饰符的规则。

$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 except domain.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修饰符相对)。
note  笔记

You can use a shorter name (alias) instead of using the full modifier name: $strict3p.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $strict3p

Compatibility  兼容性

Rules with the $strict-third-party modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.16 or later.
使用CoreLibs v1.16 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持带有$strict-third-party修饰符的规则。

$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.comexample.org发出的请求就是第三方请求。

note  笔记

To be considered as such, a third-party request should meet one of the following conditions:
要被视为此类请求,第三方请求应满足以下条件之一:

  1. Its referrer is not a subdomain of the target domain or vice versa. For example, a request to subdomain.example.org from example.org is not a third-party request
    它的引荐来源网址不是目标域的子域,反之亦然。例如,从example.orgsubdomain.example.org的请求不是第三方请求
  2. Its Sec-Fetch-Site header is set to cross-site
    Sec-Fetch-Site标头设置为cross-site

Examples  示例

$third-party:
$third-party

  • ||domain.com^$third-party — this rule applies to all domains, except domain.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 to domain.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
note  笔记

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 to evil.com or evil.org and their subdomains with a path matching /ads.
    /ads$to=evil.com|evil.org阻止任何对evil.comevil.org及其子域的请求,其路径与/ads匹配。
  • /ads$to=~not.evil.com|evil.com blocks any request to evil.com and its subdomains, with a path matching /ads, except requests to not.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 to good.com or good.org and their subdomains.
    /ads$to=~good.com|~good.org阻止路径与/ads匹配的任何请求,但对good.comgood.org及其子域的请求除外。
Restrictions  限制

$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

Compatibility  兼容性

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.
有一组修饰符,可用于将规则的应用范围限制为特定类型的内容。这些修饰符还可以组合起来以覆盖例如图像和脚本。

Compatibility  兼容性

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 from example.org.
    ||example.org^$image — 对应于example.org中的所有图像。
  • ||example.org^$script,stylesheet — corresponds to all the scripts and styles from example.org.
    ||example.org^$script,stylesheet — 对应于example.org中的所有脚本和样式。
  • ||example.org^$~image,~script,~stylesheet — corresponds to all requests to example.org except for the images, scripts and styles.
    ||example.org^$~image,~script,~stylesheet — 对应于对example.org的所有请求,图像、脚本和样式除外。
Modifier \ Products  改性剂\产品CoreLibs apps  CoreLibs 应用程序AdGuard for Chromium  适用于 Chromium 的 AdGuardAdGuard for Chrome MV3  适用于 Chrome 的 AdGuard MV3AdGuard for Firefox  适用于 Firefox 的 AdGuardAdGuard for iOS  iOS 版 AdGuardAdGuard for Safari  适用于 Safari 的 AdGuardAdGuard Content Blocker  AdGuard 内容拦截器
$document  $文档
$font  $字体
$image  $图像
$media  $媒体
$object  $对象
$other  $其他
$ping*[1]
$script  $脚本
$stylesheet  $样式表
$subdocument  $子文档*[2]
$websocket*[3]*[3]
$xmlhttprequest  $xmlhttp请求
$webrtc 🚫  $webrtc🚫
$object-subrequest 🚫  $对象子请求🚫
note  笔记
  • ✅ — 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 at example.com and all subdomains.
    @@||example.com^$document完全禁用对example.com和所有子域的所有页面的过滤。

  • ||example.com^$document blocks HTML document request to example.com with a blocking page.
    ||example.com^$document使用阻止页面阻止对example.com HTML 文档请求。

  • ||example.com^$document,redirect=noopframe redirects HTML document request to example.com to an empty html document.
    ||example.com^$document,redirect=noopframe 将对example.com HTML 文档请求重定向到空 html 文档。

  • ||example.com^$document,removeparam=test removes test query parameter from HTML document request to example.com.
    ||example.com^$document,removeparam=test 从对example.com的 HTML 文档请求中删除test查询参数。

  • ||example.com^$document,replace=/test1/test2/ replaces test1 with test2 in HTML document request to example.com.
    ||example.com^$document,replace=/test1/test2/ 在对example.com的 HTML 文档请求中将test1替换为test2

note  笔记

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修饰符限制
Limitations  局限性

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

Compatibility  兼容性

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 文件请求。

note  笔记

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 标签frameiframe

Examples  示例

  • ||example.com^$subdocument blocks built-in page requests (frame and iframe) to example.com and all its subdomains anywhere.
    ||example.com^$subdocument阻止对example.com及其所有子域的内置页面请求( frameiframe )。
  • ||example.com^$subdocument,domain=domain.com blocks built-in page requests (frame и iframe) to example.com (and its subdomains) from domain.com and all its subdomains.
    ||example.com^$subdocument,domain=domain.com 阻止从domain.com及其所有子域到example.com (及其子域)的内置页面请求( frameiframe )。
note  笔记

You may use a shorter name (alias) instead of using the full modifier name: $frame.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $frame

$subdocument modified limitations
$subdocument修改限制
Limitations  局限性

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 标头会检测子文档(如果存在)。否则,某些主页可能会被视为子文档。

Compatibility  兼容性

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修饰符限制
Limitations  局限性

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 或更高版本的设备上受支持。

Compatibility  兼容性

$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发送的请求)。

note  笔记

You may use a shorter name (alias) instead of using the full modifier name: $xhr.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $xhr

Compatibility  兼容性

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 (已删除)

Removal notice  移除通知

$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 (已删除)

Removal notice  移除通知

This modifier is removed and is no longer supported. Rules with it are considered as invalid. If you need to suppress WebRTC, consider using the nowebrtc scriptlet.
此修饰符已被删除并且不再受支持。带有它的规则被认为是无效的。如果您需要抑制 WebRTC,请考虑使用nowebrtc scriptlet

The rule applies only to WebRTC connections.
该规则仅适用于 WebRTC 连接。

Examples  示例

  • ||example.com^$webrtc,domain=example.org blocks webRTC connections to example.com from example.org.
    ||example.com^$webrtc,domain=example.org 阻止从example.orgexample.com webRTC 连接。
  • @@*$webrtc,domain=example.org disables the RTC wrapper for example.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.
例外规则禁用它们对应的地址的其他基本规则。它们以@@标记开头。上面列出的所有基本修饰符都可以应用于它们,并且它们还有一些特殊修饰符。

Visual representation  视觉表现

We recommend to get acquainted with the Adblock Plus filter cheatsheet, for better understanding of how exception rules should be made.
我们建议您熟悉Adblock Plus 过滤器备忘单,以便更好地了解如何制定例外规则。

Modifier \ Products  改性剂\产品CoreLibs apps  CoreLibs 应用程序AdGuard for Chromium  适用于 Chromium 的 AdGuardAdGuard for Chrome MV3  适用于 Chrome 的 AdGuard MV3AdGuard for Firefox  适用于 Firefox 的 AdGuardAdGuard for iOS  iOS 版 AdGuardAdGuard for Safari  适用于 Safari 的 AdGuardAdGuard Content Blocker  AdGuard 内容拦截器
$content  $内容
$elemhide
$extension  $扩展名
$jsinject  $js注入*[1]
$stealth  $隐秘
$urlblock*[2]*[2]
$genericblock*[3]*[3]
$generichide
$specifichide  $特定隐藏
note  笔记
  • ✅ — 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 at example.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 at example.com and all subdomains.
    @@||example.com^$elemhide禁用example.com和所有子域页面上的所有修饰规则。
note  笔记

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"
note  笔记

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 the AdGuard Assistant userscript on example.com website.
    @@||example.com^$extension="AdGuard Assistant" 禁用example.com网站上的AdGuard Assistant脚本。
  • @@||example.com^$extension=MyUserscript disables the MyUserscript userscript on example.com website.
    @@||example.com^$extension=MyUserscript 禁用example.com网站上的MyUserscript用户脚本。
  • @@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker' disables both AdGuard Assistant and AdGuard Popup Blocker userscripts on example.com website.
    @@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker' 禁用example.com网站上的AdGuard AssistantAdGuard Popup Blocker用户脚本。
  • @@||example.com^$extension=~"AdGuard Assistant" disables all user scripts on example.com website, except AdGuard Assistant.
    @@||example.com^$extension=~"AdGuard Assistant" 禁用example.com网站上的所有用户脚本AdGuard Assistant除外)。
  • @@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker" disables all user scripts on example.com website, except AdGuard Assistant and AdGuard Popup Blocker.
    @@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker" 禁用example.com网站上的所有用户脚本,除了AdGuard AssistantAdGuard Popup Blocker
  • @@||example.com^$extension no userscript will work on webpages on example.com.
    @@||example.com^$extension任何用户脚本都无法在example.com上的网页上运行。
  • @@||example.com^$extension="AdGuard \"Assistant\"" disables the AdGuard "Assistant" userscript on example.com website.
    @@||example.com^$extension="AdGuard \"Assistant\"" 禁用example.com网站上的AdGuard "Assistant"用户脚本。
Compatibility  兼容性
  • 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 at example.com and all subdomains.
    @@||example.com^$jsinject禁用example.com和所有子域页面上的 javascript。
$jsinject modifier limitations
$jsinject修饰符限制
Limitations  局限性

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引擎中使用它们来禁用某些修饰规则。

Compatibility  兼容性

The $jsinject modifier is not supported by AdGuard for Chrome MV3 (yet) and AdGuard Content Blocker.
AdGuard for Chrome MV3()和 AdGuard Content Blocker 不支持$jsinject修饰符。

$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:
可用修饰符选项列表:

Examples  示例

  • @@||example.com^$stealth disables Tracking protection for example.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 to domain.com (and its subdomains) on example.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 for example.com.
    @@||example.com^$stealth=3p-cookie|dpi 禁用对example.com的第三方 cookie 和 DPI 欺骗措施的阻止。
note  笔记

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

Restrictions  限制
  • 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 and 3p-cookie options.
    AdGuard 浏览器扩展仅支持searchqueriesdonottrackreferrerxclientdata1p-cookie3p-cookie选项。
Compatibility  兼容性
  • 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 at example.com and all subdomains are not going to be blocked.
    @@||example.com^$urlblock — 从example.com页面和所有子域发送的任何请求都不会被阻止。
$urlblock modifier limitations
$urlblock修饰符限制
Limitations  局限性

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 排除— 解锁所有内容。

Compatibility  兼容性

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 at example.com and all subdomains.
    @@||example.com^$genericblock禁用example.com和所有子域的任何页面上的通用基本规则。
$genericblock modifier limitations
$genericblock修饰符限制
Limitations  局限性

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 排除— 解锁所有内容。

Compatibility  兼容性

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 at example.com and its subdomains.
    @@||example.com^$generichide禁用example.com及其子域的任何页面上的通用修饰规则。
note  笔记

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 disables example.org##.banner but not ##.banner.
    @@||example.org^$specifichide禁用example.org##.banner但不禁用##.banner
note  笔记

You may use a shorter name (alias) instead of using the full modifier name: $shide.
您可以使用较短的名称(别名)而不是使用完整的修饰符名称: $shide

note  笔记

All cosmetic rules — not just specific ones — can be disabled by $elemhide modifier.
所有修饰规则(不仅仅是特定的规则)都可以通过$elemhide修饰符禁用。

Compatibility  兼容性

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 的 AdGuardAdGuard for Chrome MV3  适用于 Chrome 的 AdGuard MV3AdGuard for Firefox  适用于 Firefox 的 AdGuardAdGuard for iOS  iOS 版 AdGuardAdGuard for Safari  适用于 Safari 的 AdGuardAdGuard 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 👎
note  笔记
  • ✅ — 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
Restrictions  限制

This modifier cannot be used as an exception with the @@ mark.
此修饰符不能与@@标记一起用作例外。

$all modifier limitations
$all修饰符限制
Limitations  局限性

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修饰符。

Compatibility  兼容性

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修饰符的规则满足以下条件,则可以禁用特定域的其他基本规则:

  1. The rule has a $domain modifier
    该规则有一个$domain修饰符
  2. 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 for example.com by /some$domain=example.com,badfilter
    /some$domain=example.com|example.org|example.ioexample.com禁用 /some$domain=example.com,badfilter
  • /some$domain=example.com|example.org|example.io is disabled for example.com and example.org by /some$domain=example.com|example.org,badfilter
    /some$domain=example.com|example.org|example.ioexample.comexample.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 for example.com and example.org by /some$domain=example.com|example.org,badfilter
    /some$domain=example.*example.comexample.org禁用 /some$domain=example.com|example.org,badfilter
  • /some$domain=example.com|example.org|example.io is NOT disabled for example.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修饰符限制
Limitations  局限性

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修饰符的规则。如果只是部分取消的话我们无法计算。示例

Compatibility  兼容性

Rules with $badfilter modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有$badfilter修饰符的规则。

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 抑制或修改CookieSet-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 by example.org; this is an equivalent to setting maxAge=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 by example.org
    @@||example.org^$cookie取消阻止example.org设置的所有 cookie
  • @@||example.org^$urlblock unblocks all cookies set by example.org and disables blocking of all requests sent from example.org
    @@||example.org^$urlblock取消阻止example.org设置的所有 cookie 并禁用阻止阻止从example.org发送的所有请求
  • @@||example.org^$cookie=concept unblocks a single cookie named concept
    @@||example.org^$cookie=concept 解锁单个名为concept的cookie
  • @@||example.org^$cookie=/^_ga_/ unblocks every cookie that matches the regular expression
    @@||example.org^$cookie=/^_ga_/ 解除阻止与正则表达式匹配的每个 cookie
Limitations  局限性

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和其他侦听器不再阻塞,因此我们无法在所有情况下删除它们。您可以检查规则是否适用于此测试

Restrictions  限制

$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-partystrict-third-partystrict-first-party

Compatibility  兼容性

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.
此修饰符完全改变了规则行为。如果应用于规则,则该规则不会阻止匹配的请求。响应标头将被修改。

info  信息

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 matching frame-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规则。
Restrictions  限制
  • 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-*指令的规则被认为是无效的。
Compatibility  兼容性

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)中删除片段的便捷方法。

note  笔记

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 pattern urlpattern. The pattern works just like the one in basic URL rules, however, the characters /, $ and , must be escaped with \ inside urlpattern.
    ||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 expression regexp. Available options 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 to text for responses from URLs matching ||example.org^.
    @@||example.org^$hls=text禁用所有$hls规则,其中$hls修饰符的值等于来自匹配||example.org^ URL 的响应的text
tip  提示

$hls rules can also be disabled by $document, $content and $urlblock exception rules.
$hls规则也可以通过$document$content$urlblock例外规则禁用。

note  笔记

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:
规范的快速摘要:

  1. An HLS playlist is a collection of text lines
    HLS 播放列表是文本行的集合
  2. A line may be empty, a comment (starts with #), a tag (also starts with #, can only be recognized by name) or a URL
    一行可以为空、注释(以#开头)、标签(也以#开头,只能通过名称识别)或 URL
  3. A URL line is called a "segment"
    URL 行称为“段”
  4. 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规则操作的一些具体要点:

  1. When a segment is removed, all of the tags that apply only to that segment are also removed
    删除某个段时,仅适用于该段的所有标签也会被删除
  2. When there is a tag that applies to multiple segments, and all of those segments are removed, the tag is also removed
    当一个标签适用于多个段,并且所有这些段都被删除时,该标签也会被删除
  3. 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 指定的所有标签,以及我们在该领域看到的一些非标准标签。任何以#开头且未被识别为标记的行都会不加修改地通过,并且不会与规则匹配
  4. 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  原始回复
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXTINF,5
preroll.ts
#UPLYNK-SEGMENT:abc123,ad
#UPLYNK-KEY:aabb1122
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#UPLYNK-SEGMENT:abc123,segment
#UPLYNK-KEY:ccdd2233
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#EXT-X-ENDLIST
Applied rules  应用规则
||example.org^$hls=preroll
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
Modified response  修改后的响应
#EXTM3U
#EXT-X-TARGETDURATION:10
#UPLYNK-SEGMENT:abc123,segment
#UPLYNK-KEY:ccdd2233
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#EXT-X-ENDLIST
Restrictions  限制
  • 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规则不适用。
Compatibility  兼容性

Rules with the $hls modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.10 or later.
使用CoreLibs v1.10 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持带有$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 expression expression from the response.
    ||example.org^$jsonprune=expression 从响应中删除与修改后的 JSONPath expression匹配的项目。

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 语法与原始语法有以下差异:

  1. Script expressions are not supported
    不支持脚本表达式
  2. 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
  3. Whitespace outside of double- or single-quoted strings has no meaning
    双引号或单引号字符串之外的空格没有意义
  4. Both double- and single-quoted strings can be used
    双引号和单引号字符串都可以使用
  5. Expressions ending with .. are not supported
    不支持以..结尾的表达式
  6. 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 to text 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异常规则禁用。

note  笔记

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  输入
{
"one": 1,
"two": {
"two three": 23,
"four five": 45
}
}
Output  输出
{
"two": {
"four five": 45
}
}
  • ||example.org^$jsonprune=\$.a[?(has ad_origin)] removes all children of a that have an ad_origin key.
    ||example.org^$jsonprune=\$.a[?(has ad_origin)] 删除a的所有具有ad_origin键的子级。
Input  输入
{
"a": [
{
"ad_origin": "https://example.org",
"b": 42
},
{
"b": 1234
}
]
}
Output  输出
{
"a": [
{
"b": 1234
}
]
}
  • ||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  输入
{
"a": {"b": {"c": {"Some key": "Some value"}, "d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Some value"}, {"Some key": "Other value"}]}
}
Output  输出
{
"a": {"b": {"d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Other value"}]}
}

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 of elems which have a property selectable by the JSONPath expression $.a.b.c.
    ||example.org^$jsonprune=\$.elems[?(has "\$.a.b.c")] 删除具有可由 JSONPath 表达式$.abc选择的属性的elems的所有子级。
Input  输入
{
"elems": [
{
"a": {"b": {"c": 123}},
"k": "v"
},
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
Output  输出
{
"elems": [
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
  • ||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")] removes all children of elems 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  输入
{
"elems": [
{
"a": {"b": {"c": 123}},
},
{
"a": {"b": {"c": "abc"}}
}
]
}
Output  输出
{
"elems": [
{
"a": {"b": {"c": 123}}
}
]
}
Restrictions  限制
  • $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规则不适用。
Compatibility  兼容性

Rules with the $jsonprune modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.10 or later.
使用CoreLibs v1.10 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持使用$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 expression expression from the response.
    ||example.org^$xmlprune=expression 从响应中删除与 XPath expression匹配的项目。

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 to text 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异常规则禁用。

note  笔记

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  输入
<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>

<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>

<book category="web">
<title lang="en">XQuery Kick Start</title>
<author>James McGovern</author>
<author>Per Bothner</author>
<author>Kurt Cagle</author>
<author>James Linn</author>
<author>Vaidyanathan Nagarajan</author>
<year>2003</year>
<price>49.99</price>
</book>

<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>

</bookstore>
Output  输出
<?xml version="1.0" encoding="UTF-8"?>

<bookstore>



<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>



<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>

</bookstore>
  • ||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  输入
<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>

<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>

<book category="web">
<title lang="en">XQuery Kick Start</title>
<author>James McGovern</author>
<author>Per Bothner</author>
<author>Kurt Cagle</author>
<author>James Linn</author>
<author>Vaidyanathan Nagarajan</author>
<year>2003</year>
<price>49.99</price>
</book>

<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>

</bookstore>
Output  输出
<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>

<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>





</bookstore>
  • ||example.org^$xmlprune=//*/@* removes all attributes from all elements.
    ||example.org^$xmlprune=//*/@* 删除所有元素的所有属性。
Input  输入
<?xml version="1.0" encoding="UTF-8"?>

<bookstore location="cy">

<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>

</bookstore>
Output  输出
<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

<book>
<title>Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>

</bookstore>
Restrictions  限制
  • $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规则不适用。
Compatibility  兼容性

Rules with the $xmlprune modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.15 or later.
使用CoreLibs v1.15 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持使用$xmlprune修饰符的规则。

$network

This is basically a Firewall-like rule allowing to fully block or unblock access to a specified remote address.
这基本上是一个类似防火墙的规则,允许完全阻止或取消阻止对指定远程地址的访问。

  1. $network rules match IP addresses only! You cannot use them to block or unblock access to a domain.
    $network规则仅匹配IP地址!您不能使用它们来阻止或取消阻止对域的访问。
  2. 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
  3. An allowlist $network rule makes AdGuard bypass data to the matching endpoint, hence there will be no further filtering at all.
    白名单$network规则使 AdGuard 绕过数据到匹配的端点,因此根本不会进行进一步的过滤。
  4. 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.
我们建议您熟悉本文,以便更好地理解正则表达式。

Restrictions  限制

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 to 174.129.166.49:3478 (but not to 174.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 to 174.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 both 8.8.8.8 and 8.8.8.4.
    /8.8.8.(:?8|4)/$network阻止访问8.8.8.88.8.8.4
Compatibility  兼容性

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.
此修饰符完全改变了规则行为。如果应用于规则,则该规则不会阻止匹配的请求。响应标头将被修改。

info  信息

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标头语法相同,但有以下例外:

  1. A comma that separates multiple features MUST be escaped — see examples below.
    分隔多个功能的逗号必须转义 - 请参阅下面的示例。
  2. 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 the HTMLMediaElement interface across example.org.
    ||example.org^$permissions=autoplay=() 不允许通过example.org上的HTMLMediaElement接口请求自动播放媒体。
  • @@||example.org/page/*$permissions=autoplay=() disables all rules with the $permissions modifier exactly matching autoplay=() 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=() because b=()\,a=() or b=() does not match with a=()\,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 across example.org and example.com.
    $domain=example.org|example.com,permissions=storage-access=()\, camera=() 不允许使用存储访问 API 请求访问未分区的 cookie 以及跨example.orgexample.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规则。
note  笔记

$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 时应用。

note  笔记

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修饰符限制
Limitations  局限性

Firefox ignores the Permissions-Policy header. For more information, see this issue.
Firefox 会忽略Permissions-Policy标头。有关更多信息,请参阅此问题

Restrictions  限制
  1. Characters forbidden in the $permissions value: $.
    $permissions值中禁止使用的字符: $
  2. $permissions is compatible with a limited set of modifiers: $domain, $important, $subdocument, and content-type modifiers.
    $permissions与一组有限的修饰符兼容: $domain$important$subdocumentcontent-type modifiers
  3. $permissions rules that do not have any content-type modifiers will match only requests where content type is document.
    没有任何内容类型修饰符$permissions规则将仅匹配内容类型为document请求。
Compatibility  兼容性
  • 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 to example.org/script.js to the resource named noopjs.
    ||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 to example.org/test.mp4 to the resource named noopmp4-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修饰符限制
Limitations  局限性

In AdGuard for Chrome MV3 allowlist rules with $redirect are not supported.
AdGuard for Chrome MV3中,不支持使用$redirect的白名单规则。

Compatibility  兼容性

$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所有其他请求将保持不变。

$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 for example.com with unsafe-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 on example.com/abcd.html.
    @@||example.com/abcd.html^$referrerpolicy 禁用example.com/abcd.html上的所有$referrerpolicy规则。
Compatibility  兼容性

Rules with the $referrerpolicy modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.12 or later.
使用CoreLibs v1.12 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持带有$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 called header-name
    ||example.org^$removeheader=header-name 删除名为header-name响应标头
  • ||example.org^$removeheader=request:header-name removes a request header called header-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会。

note  笔记

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 removes Refresh header from all HTTP responses returned by example.org and its subdomains.
    ||example.org^$removeheader=refreshexample.org及其子域返回的所有 HTTP 响应中删除Refresh标头。

  • ||example.org^$removeheader=request:x-client-data removes X-Client-Data header from all HTTP requests.
    ||example.org^$removeheader=request:x-client-data 从所有 HTTP 请求中删除X-Client-Data标头。

  • Next block of rules removes Refresh and Location headers from all HTTP responses returned by example.org save for requests to example.org/path/*, for which no headers will be removed:
    下一个规则块将从example.org返回的所有 HTTP 响应中删除RefreshLocation标头,保存对example.org/path/*的请求,不会删除任何标头:

    ||example.org^$removeheader=refresh
    ||example.org^$removeheader=location
    @@||example.org/path/$removeheader
Restrictions  限制

This type of rules can only be used in trusted filters.
这种类型的规则只能在受信任的过滤器中使用。

  1. 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
  2. $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 。具有任何其他修饰符的规则将被视为无效并被丢弃。

Compatibility  兼容性

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

note  笔记

$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 中删除查询参数。请注意,此类规则仅适用于GETHEADOPTIONS ,有时还适用于POST请求。

Syntax  句法

Basic syntax  基本语法

  • $removeparam=param removes query parameter with the name param from URLs of any request, e.g. a request to http://example.com/page?param=1&another=2 will be transformed into http://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 the regexp regular expression from URLs of any request. Unlike basic syntax, it means "remove query parameters normalized to a name=value string which match the regexp regular expression". [options] here is the list of regular expression options. At the moment, the only supported option is i 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: \,.
不要忘记在正则表达式中转义,/$等特殊字符。为此目的使用\字符。例如,转义逗号应如下所示: \,

note  笔记

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,则它不是选项分隔符:

  1. It looks like $/
    看起来像$/
  2. There is another slash character / to the left of it
    其左侧还有一个斜杠字符/
  3. 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 from param.
    $removeparam=~param — 删除名称与param不同的所有查询参数。
  • $removeparam=~/regexp/ — removes all query parameters that do not match the regexp 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 removes utm_source query parameter from all requests.
    $removeparam=utm_source从所有请求中删除utm_source查询参数。

  • $removeparam=/utm_.*/ removes all utm_* query parameters from URL queries of any request, e.g. a request to http://example.com/page?utm_source=test will be transformed to http://example.com/page.
    $removeparam=/utm_.*/从任何请求的 URL 查询中删除所有utm_* query参数,例如请求 http://example.com/page?utm_source=test 将转换为http://example.com/page

  • $removeparam=/^utm_source=campaign$/ removes utm_source query parameter with the value equal to campaign. It does not touch other utm_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修饰符限制
Limitations  局限性

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=p1case2

    is 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
    }
    }
    ]
Restrictions  限制
  1. Rules with the $removeparam modifier can only be used in trusted filters.
    带有$removeparam修饰符的规则只能在受信任的过滤器中使用。
  2. $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修饰符兼容。具有任何其他修饰符的规则将被视为无效并将被丢弃。
  3. $removeparam rules without content type modifiers will only match requests where the content type is document.
    不带内容类型修饰符$removeparam规则将仅匹配内容类型为document请求。
Compatibility  兼容性
  • 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规则适用于任何文本响应,但不适用于二进制( mediaimageobject等)。
  • $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 to regexp.
    replacement — 将用于替换与regexp对应的字符串的字符串。
  • modifiers — a regular expression flags. For example, i — insensitive search, or s — 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>其中$被转义;
  • modifiersi 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规则

  1. ||example.org^$replace=/X/Y/
  2. ||example.org^$replace=/Z/Y/
  3. @@||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 of example.org including the page itself.
    @@||example.org^$document@@||example.org^$content将禁用源自example.org页面(包括页面本身)的所有$replace规则。
Restrictions  限制

Rules with the $replace modifier can only be used in trusted filters.
带有$replace修饰符的规则只能在受信任的过滤器中使用。

Compatibility  兼容性

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 to regexp.
    replacement — 将用于替换与regexp对应的字符串的字符串。
  • modifiers — a regular expression flags. For example, i — insensitive search, or s — 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  改变原点

Compatibility  兼容性

This section only applies to AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.17 or later.
本部分仅适用于带有CoreLibs v1.17 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android。

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其中$被转义;
  • modifiersi for insensitive search.
    modifiers - i表示不敏感搜索。

Multiple $urltransform rules
多个$urltransform规则

  1. ||example.org^$urltransform=/X/Y/
  2. ||example.org^$urltransform=/Z/Y/
  3. @@||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会。

Restrictions  限制

Rules with the $urltransform modifier can only be used in trusted filters.
带有$urltransform修饰符的规则只能在受信任的过滤器中使用。

Compatibility  兼容性

Rules with the $urltransform modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.15 or later.
使用CoreLibs v1.15 或更高版本的 AdGuard for Windows、AdGuard for Mac 和 AdGuard for Android 支持使用$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
Compatibility  兼容性

Rules with noop modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有noop修饰符的规则。

$empty (deprecated)
$empty (已弃用)

Deprecation notice  弃用通知

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 to example.org and all subdomains.
    ||example.org^$emptyexample.org和所有子域的所有请求返回空响应。
Compatibility  兼容性

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 (已弃用)

Deprecation notice  弃用通知

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/*的所有视频下载,并更改对视频占位符的响应。
Compatibility  兼容性

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.
每个规则都有自己的优先级,当有多个规则与请求匹配并且过滤引擎需要选择其中之一时,这是必要的。优先级用正整数来衡量。

Collisions  碰撞

When two rules with the same priority match the same request, the filter engine implementation determines which one is chosen.
当具有相同优先级的两个规则匹配相同的请求时,过滤器引擎实现确定选择哪一个。

info  信息

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。如果计算出的优先级是浮点数,则会向上舍入到大于或等于计算出的优先级的最小整数。

Compatibility  兼容性
  • 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 依赖于浏览器实现,它们无法遵循此处指定的规则。
note  笔记

Modifier aliases (1p, 3p, etc.) are not included in these categories, however, they are utilized within the engine to compute the rule priority.
修饰符别名( 1p3p等)不包含在这些类别中,但是,它们在引擎中用于计算规则优先级。

Basic modifiers, the presence of each adds 1 to the priority
基本修饰符,每个修饰符的存在都会使优先级加 1

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:  所有有效的内容类型:

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的特定异常:

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  具体例外情况

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.
其他修饰符应该对请求执行额外的后处理或预处理,不会向规则优先级添加任何内容。

note  笔记

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  示例

  1. ||example.com^

    Weight of the rule without modifiers: 1.
    没有修饰符的规则的权重: 1

  2. ||example.com^$match-case

    Rule weight: base weight + weight of the modifier from category 1: 1 + 1 = 2.
    规则权重:基础权重 +类别 1中修饰符的权重: 1 + 1 = 2

  3. ||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

  4. ||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

  5. @@||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不参与优先级计算 + 允许的内容类型,类别 21 + 10000 + 0 + (50 + 50 / 1) = 10101

  6. @@||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 + 允许的域,类别 31 + 10000 + 1000000 + (100 + 100 / 2) = 1010152 .

  7. @@||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 + 两种允许的内容类型(文档和子文档),类别 21 + 10000 * 4 + (50 + 50 / 2) = 40076 .

  8. *$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 + 拒绝,类别 11 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303 .

  9. ||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 代码而不破坏任何内容。本节中描述的规则是专门为此目的而创建的。

Categories \ Products  类别 \ 产品CoreLibs apps  CoreLibs 应用程序AdGuard for Chromium  适用于 Chromium 的 AdGuardAdGuard for Chrome MV3  适用于 Chrome 的 AdGuard MV3AdGuard for Firefox  适用于 Firefox 的 AdGuardAdGuard for iOS  iOS 版 AdGuardAdGuard for Safari  适用于 Safari 的 AdGuardAdGuard Content Blocker  AdGuard 内容拦截器
Element hiding  元素隐藏
CSS rules  CSS 规则
Extended CSS  扩展CSS
HTML filtering  HTML过滤
JavaScript
Scriptlets  小脚本
note  笔记
  • ✅ — fully supported  ✅ — 完全支持
  • ❌ — not supported  ❌ — 不支持

Cosmetic rules  化妆品规则

info  信息

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]]]
  • selectorCSS selector, defines the elements to be hidden.
    selectorCSS 选择器,定义要隐藏的元素。
  • 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.orgexample.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

note  笔记

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 a div with the class textad at example.com and all subdomains.
    example.com##div.textad — 隐藏example.com和所有子域中包含textad类的div
  • example.com,example.org###adblock — hides an element with attribute id equals adblock at example.com, example.org and all subdomains.
    example.com,example.org###adblock — 在example.comexample.org和所有子域中隐藏属性id等于adblock元素。
  • ~example.com##.textad — hides an element with the class textad at all domains, except example.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]]]
  • selectorCSS selector, that defines the elements we want to apply the style to.
    selectorCSS 选择器,定义我们想要应用样式的元素。
  • 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 规则本身时才使用此类例外。在其他情况下,最好使用域限制来更改原始规则。

Restrictions  限制

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>类型的值。

Compatibility  兼容性

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 选择器

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 规则

Compatibility  兼容性

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 all div elements containing a child node that has a link with the attributes [target="_blank"][rel="nofollow"]. The rule applies only to example.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 style display: none!important to all h3 elements that contain the word cookies. The rule applies only to example.com and all its subdomains.
    example.com#$?#h3:contains(cookies) { display: none!important; } — 此规则设置样式display: none!important对于所有包含单词cookiesh3元素。该规则仅适用于example.com及其所有子域。
  • example.net#?#.banner:matches-css(width: 360px) — this rule blocks all .banner elements with the style property width: 360px. The rule applies only to example.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.
了解有关如何调试扩展选择器的更多信息。

note  笔记

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 限制

  1. CSS comments and at-rules are not supported.
    不支持 CSS注释at 规则

  2. 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()伪类。不幸的是,并非所有流行的浏览器都支持它

note  笔记

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 支持以获得更好的兼容性。

Removal notice  移除通知

: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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • selector — required, standard or extended CSS selector
    selector — 必需的、标准的或扩展的 CSS 选择器

The pseudo-class :has() selects the target elements that fit to the selector. Also the selector can start with a combinator.
伪类:has()选择适合selectortarget元素。 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>
Old syntax  旧语法

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()伪类原理非常简单:它允许选择包含指定文本或内容与指定正则表达式匹配的元素。支持正则表达式标志。

note  笔记

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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • match — required, string or regular expression for matching element textContent. 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)
note  笔记

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=matchdiv ,因为下一个元素不包含任何文本,并且banner是代码的一部分,而不是文本。

Old syntax  旧语法

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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • pseudo-element — optional, valid standard pseudo-element, e.g. before, after, first-line, etc.
    pseudo-element — 可选的、有效的标准伪元素,例如beforeafterfirst-line等。
  • property — required, a name of CSS property to check the element for
    property — 必需的,用于检查元素的 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/)
Restrictions  限制

Regexp patterns do not support flags.
正则表达式模式不支持标志。

Compatibility  兼容性

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()但仍然支持以获得更好的兼容性。

Old syntax  旧语法

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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • name — required, simple string or string with wildcard or regular expression for attribute name matching
    name — 必需的,简单字符串带有通配符正则表达式的字符串,用于属性名称匹配
  • value — optional, simple string or string with wildcard or regular expression for attribute value matching
    value — 可选的简单字符串带有通配符正则表达式的字符串,用于属性值匹配

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>
Restrictions  限制

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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • name — required, simple string or string with wildcard or regular expression for element property name matching
    name — 必需的,简单字符串带有通配符正则表达式的字符串,用于元素属性名称匹配
  • value — optional, simple string or string with wildcard or regular expression for element property value matching
    value — 可选的简单字符串带有通配符正则表达式的字符串,用于元素属性值匹配

Escaping special characters
转义特殊字符

For regexp patterns " and \ must be escaped, e.g. div:matches-property(prop=/[\\w]{4}/).
对于正则表达式模式"\必须转义,例如 div:matches-property(prop=/[\\w]{4}/)

note  笔记

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/)
For filter maintainers  对于过滤器维护人员

To check properties of a specific element, do the following:
要检查特定元素的属性,请执行以下操作:

  1. Inspect the page element or select it in Elements tab of browser DevTools
    检查页面元素或在浏览器 DevTools 的Elements选项卡中选择它
  2. Run console.dir($0) in Console tab
    Console选项卡中运行console.dir($0)
Restrictions  限制

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 selector
    target - 可选、标准或扩展 CSS 选择器
  • expression — required, valid XPath expression
    expression — 必需的、有效的 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 selector
    subject — 必需的、标准的或扩展的 CSS 选择器
  • n — required, number >= 1 and < 256, distance to the needed ancestor from the element selected by subject
    n — 必需,数字 >= 1 且 < 256,从subject选择的元素到所需祖先的距离

Syntax  句法

subject:nth-ancestor(n)
  • subject — required, standard or extended CSS selector
    subject — 必需的、标准的或扩展的 CSS 选择器
  • n — required, number >= 1 and < 256, distance to the needed ancestor from the element selected by subject
    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#target1div[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 selector
    subject — 必需的、标准的或扩展的 CSS 选择器
  • ancestor — required, specification for the ancestor of the element selected by subject, 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 选择器
: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 selector
    selector — 必需的、标准的或扩展的 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; }
note  笔记

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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • selectorsforgiving 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 element
    target — 可选、标准或扩展 CSS 选择器,可以跳过检查任何元素
  • selectors — list of standard or extended selectors
    selectors — 标准或扩展选择器列表
: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() (已删除)

Removal notice  移除通知

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 元素。

Compatibility  兼容性

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 or script.
    tagName — 小写的元素名称,例如divscript
  • 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, the selector on the right of the combinator will only match an element whose direct parent matches the selector on the left of the combinator.
    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

Deprecation notice  弃用通知

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"]
Limitations  局限性

The tag-content special attribute must not appear in a selector to the left of a > combinator.
tag-content特殊属性不得出现在>组合符左侧的选择器中。

wildcard

Deprecation notice  弃用通知

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是否包含两个连续的子字符串bannertext

Limitations  局限性

The wildcard special attribute must not appear in a selector to the left of a > combinator.
wildcard特殊属性不得出现在>组合符左侧的选择器中。

max-length

Deprecation notice  弃用通知

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元素。

Limitations  局限性

The max-length special attribute must not appear in a selector to the left of a > combinator.
max-length特殊属性不得出现在>组合符左侧的选择器中。

min-length

Deprecation notice  弃用通知

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元素。

Limitations  局限性

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)?/)
Compatibility  兼容性

:-abp-contains() and :has-text() are synonyms for :contains().
:-abp-contains():has-text():contains()的同义词。

Compatibility  兼容性

The :contains() pseudo-class is supported by AdGuard for Windows, Mac, and Android with CoreLibs v1.13 or later.
:contains()伪类受适用于 Windows、Mac 和 Android 的CoreLibs v1.13 或更高版本的 AdGuard 支持。

Requires that the inner HTML of the element contains the specified text or matches the specified regular expression.
要求元素的内部 HTML 包含指定的文本或与指定的正则表达式匹配。

Limitations  局限性

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 code window.__gaq = undefined; on all pages at example.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.
我们建议仅当无法更改隐藏规则本身时才使用此类例外。在其他情况下,最好使用域限制来更改原始规则。

Restrictions  限制

JavaScript rules can only be used in trusted filters.
JavaScript 规则只能在受信任的过滤器中使用。

Compatibility  兼容性

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 过滤规则中以声明方式使用。

note  笔记

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 of string arguments (no other types of arguments are supported).
    arguments — 可选, string参数列表(不支持其他类型的参数)。

Examples  示例

  1. Apply the abort-on-property-read scriptlet on all pages of example.org and its subdomains, and pass it an alert argument:
    example.org及其子域的所有页面上应用abort-on-property-read脚本,并向其传递一个alert参数:

    example.org#%#//scriptlet('abort-on-property-read', 'alert')
  2. Remove the branding class from all div[class^="inner"] elements on all pages of example.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 of string arguments to match the same blocking rule and disable it.
    arguments — 可选, string参数列表,用于匹配相同的阻止规则并禁用它。

Examples  示例

  1. Disable specific scriptlet rule so that only abort-on-property-read is applied only on example.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")
  2. Disable all abort-on-property-read scriptlets for example.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")
  3. 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()
  4. Apply set-constant and set-cookie to any web page, but due to special scriptlet exception rule only the set-constant scriptlet will be applied on example.org and its subdomains:
    set-constantset-cookie应用到任何网页,但由于特殊的 scriptlet 例外规则,只有set-constant scriptlet 将应用于example.org及其子域:

    #%#//scriptlet('set-constant', 'adList', 'emptyArr')
    #%#//scriptlet('set-cookie', 'accepted', 'true')
    example.org#@%#//scriptlet('set-cookie')
  5. Apply adjust-setInterval to any web page and set-local-storage-item on example.com and its subdomains, but there are also multiple scriptlet exception rules, so no scriptlet rules will be applied on example.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 上找到。

Compatibility  兼容性

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 轻松区分。

note  笔记

Trusted scriptlets are not compatible with other ad blockers except AdGuard.
受信任的 scriptlet 与除 AdGuard 之外的其他广告拦截器不兼容。

Restrictions  限制

Trusted scriptlets rules can only be used in trusted filters.
受信任的 scriptlet 规则只能在受信任的过滤器中使用。

Compatibility  兼容性

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: \].
在修饰符值中,必须对以下字符进行转义: [],\ (除非用于转义)。使用\来转义它们。例如,转义括号如下所示: \]

Modifier \ Products  改性剂\产品CoreLibs apps  CoreLibs 应用程序AdGuard for Chromium  适用于 Chromium 的 AdGuardAdGuard for Chrome MV3  适用于 Chrome 的 AdGuard MV3AdGuard for Firefox  适用于 Firefox 的 AdGuardAdGuard for iOS  iOS 版 AdGuardAdGuard for Safari  适用于 Safari 的 AdGuardAdGuard Content Blocker  AdGuard 内容拦截器
$app  $应用程序
$domain  $域名*[1]
$path  $路径
$url  $网址*[2]*[2]*[2]
note  笔记
  • ✅ — 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 a div with the class textad at example.com and all subdomains in requests sent from the org.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 a div with the class textad at example.com and all subdomains in requests sent from any app except org.example.app1 and org.example.app2.
    [$app=~org.example.app1|~org.example.app2]example.com##.textad 隐藏example.com中类为textad div以及从除org.example.app1org.example.app2之外的任何应用程序发送的请求中的所有子域。
  • [$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300') applies scriptlet prevent-setInterval only in Safari browser on Mac.
    [$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300') 仅在 Mac 上的 Safari 浏览器中应用 scriptlet prevent-setInterval
  • [$app=org.example.app]#@#.textad disables all ##.textad rules for all domains while using org.example.app.
    [$app=org.example.app]#@#.textad 使用org.example.app时禁用所有域的所有##.textad规则。
Compatibility  兼容性

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 a div with the class textad at example.com and all subdomains.
    [$domain=example.com]##.textad — 在example.com和所有子域中隐藏带有类textaddiv
  • [$domain=example.com|example.org]###adblock — hides an element with attribute id equals adblock at example.com, example.org and all subdomains.
    [$domain=example.com|example.org]###adblock — 在example.comexample.org和所有子域中隐藏属性id等于adblock元素。
  • [$domain=~example.com]##.textad — this rule hides div elements of the class textad for all domains, except example.com and its subdomains.
    [$domain=~example.com]##.textad — 此规则隐藏所有域的textad类的div元素,但example.com及其子域除外。

There are 2 ways to specify domain restrictions for non-basic rules:
有两种方法可以指定非基本规则的域限制:

  1. the "classic" way is to specify domains before rule mask and attributes: example.com##.textad;
    “经典”方法是在规则掩码和属性之前指定域: example.com##.textad
  2. 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修饰符限制

Limitations  局限性

Since the non-basic $domain works the same as the basic one, it has the same limitations.
由于非基本$domain工作方式与基本 $domain 相同,因此它具有相同的限制

Compatibility  兼容性

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 a div with the class textad 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处隐藏带有类textaddiv
  • [$path=/page.html]##.textad hides a div with the class textad 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处隐藏类textaddiv ,但不在/another_page.html/another_page.html
  • [$path=|/page.html]##.textad hides a div with the class textad 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 a div with the class textad 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 a div with the class textad at /page1.html or /page2.html or any other path matching /page<...>.html of example.com
    [$path=/page*.html]example.com##.textad/page1.html/page2.html或与example.com/page<...>.html匹配的任何其他路径中隐藏带有类textad div
  • [$path]example.com##.textad hides a div with the class textad at the main page of example.com
    [$path]example.com##.textadexample.com的主页上隐藏了一个带有textad类的div
  • [$domain=example.com,path=/page.html]##.textad hides a div with the class textad at page.html of example.com and all subdomains but not at another_page.html
    [$domain=example.com,path=/page.html]##.textadexample.com和所有子域的page.html处隐藏带有类textad div ,但不在another_page.html处隐藏
  • [$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad hides a div with the class textad 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处隐藏带有类textaddiv (请注意转义的特殊字符
Compatibility  兼容性

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 a div with the class textad at addresses like https://example.com/content/article.html and even https://subdomain.example.com/content/article.html.
    [$url=||example.com/content/*]##div.textad 隐藏一个带有类textaddiv ,地址如下 https://example.com/content/article.html 甚至 https://subdomain.example.com/content/article.html
  • [$url=||example.org^]###adblock hides an element with attribute id equal to adblock at example.org and its subdomains.
    [$url=||example.org^]###adblockexample.org及其子域中隐藏属性id等于adblock的元素。
  • [$url=/\[a-z\]+\\.example\\.com^/]##.textad hides div elements of the class textad 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修饰符限制

Limitations  局限性

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 将不会被应用。

Compatibility  兼容性

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:
我们提供预处理器指令,过滤器维护人员可以使用这些指令来提高与不同广告拦截器的兼容性,并提供:

note  笔记

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:
有两种可能的情况:

  1. 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指令之间的代码。

  2. 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之间的代码将被编译。

note  笔记

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 cases
      adguard始终声明;向维护者展示这是 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 Windows
        adguard_app_windows — AdGuard Windows 版
      • adguard_app_mac — AdGuard for Mac
        adguard_app_mac — Mac 版 AdGuard
      • adguard_app_android — AdGuard for Android
        adguard_app_android — 适用于 Android 的 AdGuard
      • adguard_app_ios — AdGuard for iOS
        adguard_app_ios — 适用于 iOS 的 AdGuard
      • adguard_ext_safari — AdGuard for Safari
        adguard_ext_safari — Safari 的 AdGuard
      • adguard_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_mv3AdGuard for Chrome MV3
        adguard_ext_chromium_mv3Chrome MV3 的 AdGuard
      • adguard_ext_firefox — AdGuard Browser Extension for Firefox
        adguard_ext_firefox — 适用于 Firefox 的 AdGuard 浏览器扩展
      • adguard_ext_edge — AdGuard Browser Extension for Edge Legacy
        adguard_ext_edge — 适用于 Edge Legacy 的 AdGuard 浏览器扩展
      • adguard_ext_opera — AdGuard Browser Extension for Opera
        adguard_ext_opera — 用于 Opera 的 AdGuard 浏览器扩展
      • adguard_ext_android_cb — AdGuard Content Blocker for mobile Samsung and Yandex browsers
        adguard_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 FiltersRegistry
        ext_ublock — 特殊情况;当FiltersRegistry编译过滤器的 uBlock 版本时声明此一个
      • cap_html_filtering — products that support HTML filtering rules: AdGuard for Windows, AdGuard for Mac, and AdGuard for Android
        cap_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 rules
    rules_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
Compatibility  兼容性

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 产品可能仍然不支持它。以下产品将在上述版本或更高版本中支持它:

  • AdGuard for Windows, Mac, and Android with CoreLibs v1.13;
    AdGuard 适用于 Windows、Mac 和 Android,带有CoreLibs v1.13;
  • AdGuard Browser Extension v4.2.208;
    AdGuard 浏览器扩展 v4.2.208;
  • AdGuard v1.11.16 for Safari.
    适用于 Safari 的 AdGuard v1.11.16。

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.
用户规则和许可名单已添加到每个内容拦截器中。

caution  警告

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 blocker
      general — AdGuard 通用内容拦截器
    • privacy — AdGuard Privacy content blocker
      privacy — AdGuard 隐私内容拦截器
    • social — AdGuard Social content blocker
      social — AdGuard 社交内容拦截器
    • security — AdGuard Security content blocker
      security — AdGuard 安全内容拦截器
    • other — AdGuard Other content blocker
      other — AdGuard 其他内容拦截器
    • custom — AdGuard Custom content blocker
      custom — AdGuard 自定义内容拦截器
    • all — special keyword that means that the rules must be included into all content blockers
      all — 特殊关键字,意味着规则必须包含在所有内容拦截器中
  • rules_list — list of rules
    rules_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
    minPercentpercent值的下限
  • maxPercent — upper bound of percent value
    maxPercentpercent值的上限
  • strict — if percent < minPercent OR percent > maxPercent and strict mode is on then filter compilation should fail, otherwise original rules must be used
    strict — 如果percent < minPercentpercent > 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 浏览器扩展的基本过滤器的两个版本:

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
PLATFORMNOT_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:
用于指定应用规则的平台。现有平台的列表以及基本过滤器的链接,例如,每个平台:

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
note  笔记

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 iOSAdGuard 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 one
    selectorParsed — 解析选择器的文本,可能与输入的不同
  • timings — list of DOM nodes matched by the selector
    timings — 选择器匹配的 DOM 节点列表
    • appliesCount — total number of times that the selector has been applied on the page
      appliesCount — 选择器在页面上应用的总次数
    • 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 page
      meanTiming — 在页面上应用选择器所花费的平均时间
    • standardDeviation — standard deviation
      standardDeviation — 标准差
    • timingsSum — total time it took to apply the selector on the page across all instances
      timingsSum — 在所有实例的页面上应用选择器所花费的总时间

Printed only for remove pseudos:
仅打印用于删除伪项:

  • removed — flag to signal if elements were removed
    removed — 标记以指示元素是否已被删除

Printed if elements are not removed:
如果元素未被删除则打印:

  • matchedElements — list of DOM nodes matched by the selector
    matchedElements — 与选择器匹配的 DOM 节点列表
  • styleApplied — parsed rule style declaration related to the selector
    styleApplied — 与选择器相关的解析规则样式声明

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 是专门为调试目的而开发的:

The following scriptlets also may be used for debug purposes:
以下 scriptlet 也可用于调试目的:

Compatibility tables legend
兼容性表图例

Product shortcuts  产品快捷键

  1. CoreLibs appsAdGuard for Windows, AdGuard for Mac, and AdGuard for Android
    CoreLibs appsAdGuard for WindowsAdGuard for MacAdGuard for Android
  2. AdGuard for ChromiumAdGuard Browser Extension for Chrome and other Chromium-based browsers such as Microsoft Edge, Opera
    AdGuard for Chromium — 适用于 Chrome 和其他基于 Chromium 的浏览器(例如 Microsoft Edge、Opera)的 AdGuard 浏览器扩展
  3. AdGuard for Chrome MV3AdGuard Browser Extension for Chrome MV3
    AdGuard for Chrome MV3适用于 Chrome MV3 的 AdGuard 浏览器扩展
  4. AdGuard for FirefoxAdGuard Browser Extension for Firefox
    AdGuard for FirefoxAdGuard Firefox 浏览器扩展
  5. AdGuard for iOSAdGuard for iOS and AdGuard Pro for iOS (for mobile Safari browser)
    AdGuard for iOSAdGuard for iOS和 AdGuard Pro for iOS(适用于移动 Safari 浏览器)
  6. AdGuard for SafariAdGuard for desktop Safari browser
    AdGuard for SafariAdGuard 适用于桌面 Safari 浏览器
  7. AdGuard Content BlockerContent Blocker for Android mobile browsers: Samsung Internet and Yandex Browser
    AdGuard Content Blocker — 适用于 Android 移动浏览器的内容拦截器:Samsung Internet 和 Yandex Browser

Compatibility shortcuts  兼容性快捷键

note  笔记
  • ✅ — 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
    🚫 — 已删除且不再受支持