这是用户在 2024-5-16 15:27 为 https://adguard.com/kb/zh-CN/general/ad-filtering/create-own-filters/ 保存的双语快照页面,由 沉浸式翻译 提供双语支持。了解如何保存?
跳转到主内容

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

信息

在本文中,我们解释如何编写用于 AdGuard 产品的自定义过滤规则。 To test your rules, you can download the AdGuard app

A filter is a set of filtering rules applied to specific content, such as banners or pop-ups. AdGuard has a list of standard filters created by our team. We constantly improve and update them, striving to meet the needs of most of our users.
过滤器是应用于特定内容(如横幅或弹出窗口)的一组过滤规则。AdGuard 有一个由我们团队创建的标准过滤器列表。我们不断改进和更新它们,努力满足大多数用户的需求。

At the same time, AdGuard allows you to create your own custom filters using the same types of rules that we have in our filters.
同时,AdGuard 允许您使用与我们过滤器中相同的规则类型创建自己的自定义过滤器。

To describe the syntax of our filtering rules, we use Augmented BNF for Syntax Specifications, but we do not always strictly follow this specification.
为了描述过滤规则的语法,我们使用增强 BNF 作为语法规范,但我们并不总是严格遵循此规范。

信息

Originally, the AdGuard's syntax was based on the syntax of Adblock Plus rules. Later, we extended it with new types of rules for better ad filtering. Some parts of this article about the rules common both to AdGuard and ABP were taken from the Adblock Plus guide on how to write filters.
最初,AdGuard 的语法是基于 Adblock Plus 规则的语法。后来,我们用新的规则类型对其进行了扩展,以便更好地过滤广告。本文中关于 AdGuard 和 ABP 通用规则的某些部分摘自 Adblock Plus 指南中关于如何编写过滤器.

Comments 评论

Any line that starts with an exclamation mark is a comment. In the list of rules it is displayed in gray color. AdGuard will ignore this line, so you can write anything you want. Comments are usually placed above the rules and used to describe what a rule does.
任何以感叹号开头的行都是注释。在规则列表中,它以灰色显示。AdGuard 将忽略此行,因此您可以编写任何您想要的内容。注释通常位于规则之上,用于描述规则的作用。

For example: 例如:

! This is the comment. Below this line, there is an actual filtering rule.
||example.org^

Examples 例子

Blocking by domain name
按域名屏蔽

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

NameCSS 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:
某些规则只能在受信任的筛选器中使用。此类别包括:

  • filter lists created by the AdGuard team,
    由 AdGuard 团队创建的过滤器列表,
  • custom filter lists installed as trusted,
    自定义筛选器列表安装为 trusted
  • user rules. 用户规则。

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 安装。不要将其与功能齐全的 AdGuard for Android 混淆,后者只能从我们的网站下载。不幸的是,AdGuard 内容拦截器功能受到浏览器允许的功能的限制,并且它们仅支持旧的 Adblock Plus 过滤器语法:

  • Basic blocking rules with the following modifiers: $domain, $third-party, content-type modifiers.
    具有以下修饰符的基本阻止规则: $domain$third-party 、 content-type 修饰符。
  • 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 内容拦截器。

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.
    ^ — 分隔符标记。分隔符是任何字符,但字母、数字或以下 _ - . 字符之一 % :。在此示例中,分隔符以粗体显示: http: // example.com /? 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 应于 。
注意

|, ||, ^ 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.
在外观、HTML 过滤和 JavaScript 规则模式中,域的 TLD 支持通配符。

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)匹配。但对于 AdGuard for Safari 和 iOS,由于 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://subdomain.example.com/ads/otherbanner.jpg 这样的 http://example.com/ads/banner.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 基本规则修饰符

注意

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 AdGuard Chromium 版AdGuard for Firefox AdGuard Firefox 版AdGuard iOS版AdGuard Safari版AdGuard 内容拦截器
$app
$denyallow
$domain**
$header
$important
$match-case
$method
$popup✅ *✅ *✅ *
$third-party $third方
$to
注意
  • ✅ — fully supported ✅ — 完全支持
  • ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
    ✅ * — 支持,但可靠性可能会有所不同或存在限制;查看修改器说明了解更多详情
  • ⏳ — feature that has been implemented or 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.app1 org.example.app2 应用程序和应用程序。

If you want the rule not to be applied to certain apps, start the app name with the ~ sign.
如果不希望将规则应用于某些应用,请以 ~ 符号开头应用名称。

  • ||baddomain.com^$app=~org.example.app — a rule to block requests that match the specified mask and are sent from any app except for 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 versions that have CoreLibs v1.12 under the hood.
    在 Windows 上,进程名称不区分大小写,从 AdGuard for Windows 版本开始,该版本具有 CoreLibs v1.12。

$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.*.
    修饰符值中的域不能被否定,例如 $denyallow=~x.com ,或具有通配符 TLD,例如 $denyallow=x.*

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.
AdGuard for iOS、Safari 和 AdGuard Content Blocker 不支持带 $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 — 以通配符结尾的域名作为公共后缀,例如,for example.* it is co.uk in example.co.uk .对应于具有任何公共后缀的指定域及其子域。它在词典上是匹配的。
  • regexp — a regular expression, starts and ends with /. The pattern works the same way as in the basic URL rules, but the characters /, $, and | must be escaped with \.
    regexp — 正则表达式,以 / 开头和结尾。该模式的工作方式与基本 URL 规则中的工作方式相同,但字符 /$| 必须用 \ 进行转义。
信息

Rules with $domain modifier as regular_domain or any_tld_domain are supported by all AdGuard products.
所有 AdGuard 产品都支持修 $domain 饰符 regular_domain any_tld_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.org 适用于 和 example.com .

If you want the rule not to be applied to certain domains, start a domain name with ~ sign.
如果您希望该规则不应用于某些域,请使用 ~ 符号启动域名。

$domain and negation ~:
$domain 和否定 ~

  • ||baddomain.com^$domain=example.org blocks requests that match the specified mask and are sent from 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.org 适用于 和 example.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)\$/ 阻止从任何域发送的请求,但具有任何公共后缀( b.comb.co.uk 等)、 c.comc.org 及其子域的 除外 a.com b

$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.org 出 和 example.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.org 出 和 example.com 的请求。

In the following examples it is implied that requests are sent from http://example.org/page (the referrer) and the target URL is http://targetdomain.com/page.
在以下示例中,暗示请求是从 http://example.org/page (反向链接)发送的,目标 URL 是 http://targetdomain.com/page

  • page$domain=example.org will be matched, as it matches the referrer domain.
    page$domain=example.org 将被匹配,因为它与反向链接域匹配。
  • page$domain=targetdomain.com will be matched, as it matches the target domain and satisfies all requirements mentioned above.
    page$domain=targetdomain.com 将被匹配,因为它与目标域匹配并满足上述所有要求。
  • ||*page$domain=targetdomain.com will not be matched, as the pattern ||*page may match specific domains, e.g. example.page.
    ||*page$domain=targetdomain.com 不会匹配,因为模式 ||*page 可能匹配特定域,例如 example.page .
  • ||*page$domain=targetdomain.com,cookie will be matched because the rule contains $cookie modifier despite the pattern ||*page may match specific domains.
    ||*page$domain=targetdomain.com,cookie 将匹配,因为规则包含 $cookie 修饰符,尽管模式 ||*page 可能匹配特定域。
  • /banner\d+/$domain=targetdomain.com will not be matched as it contains a regular expression.
    /banner\d+/$domain=targetdomain.com 不会匹配,因为它包含正则表达式。
  • page$domain=targetdomain.com|~example.org will not be matched because the referrer domain is explicitly excluded.
    page$domain=targetdomain.com|~example.org 不会匹配,因为反向链接域被显式排除。
$domain modifier limitations
$domain 编辑限制
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 不支持同时使用允许和不允许的域,因此 ad Guard for iOS 和 AdGuard for Safari 中不起作用 ||baddomain.com^$domain=example.org|~foo.example.org

Compatibility 兼容性

Rules with regular expressions in the $domain modifier are supported by AdGuard for Windows, Mac, and Android, running CoreLibs v1.11 or later.
运行 CoreLibs v1.11 或更高版本的 Windows、Mac 和 Android 版 AdGuard 支持 $domain 修饰符中包含正则表达式的规则。

In AdGuard for Windows, Mac and Android running 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-insesitively.
    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 的标头的请求。
Compatibility 兼容性

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

$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, running SafariConverterLib v2.0.43 or later.
运行 SafariConverterLib v2.0.43 或更高版本的 AdGuard for iOS 和 AdGuard for Safari 支持带有 的规则 $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 rejected.
具有混合否定值和非否定值的规则被视为无效。因此,例如,该规则 ||evil.com^$method=get|~head 将被拒绝。

Compatibility 兼容性

Rules with $method modifier are supported by AdGuard for Windows, Mac, and Android with CoreLibs v1.12 or later and AdGuard Browser Extension for Chrome, Firefox, and Edge with TSUrlFilter v2.1.1 or later.
带有 CoreLibs v1.12 或更高版本的 AdGuard for Windows、Mac 和 Android 以及带有 TSUrlFilter v2.1.1 或更高版本的 AdGuard Browser Extension for Chrome、Firefox 和 Edge 支持带 $method 修饰符的规则。

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/ ,则此规则将关闭必须打开指定站点的新选项卡。
Compatibility 兼容性
  • $popup modifier works best in AdGuard Browser Extension.
    $popup modifier 在 AdGuard 浏览器扩展中效果最佳。
  • In AdGuard for Safari and iOS, $popup rules simply block the page right away.
    在 AdGuard for Safari 和 iOS 中, $popup 规则只是立即阻止页面。
  • In AdGuard for Windows, Mac, and Android, $popup modifier may not detect a popup in some cases and it will not be blocked. $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 and $important.
    在 AdGuard for Windows、Mac 和 Android 中, $popup 修改器在某些情况下可能无法检测到弹出窗口,并且不会被阻止。 $popup 修饰符应用带有特殊标志的内容 document 类型,该标志将传递给阻止页面。阻止页面本身可以进行一些检查并关闭窗口,如果它真的是一个弹出窗口。否则,应加载页面。它可以与其他请求类型修饰符(如 $third-party$important )结合使用。
  • Rules with $popup modifier are not supported by AdGuard Content Blocker.
    AdGuard 内容拦截器不支持带有 $popup 修饰符的规则。

$third-party

A restriction of third-party and own requests. A third-party request is a request from a different domain. For example, a request to example.org from domain.com is a third-party request.
对第三方和自己的请求的限制。第三方请求是来自其他域的请求。例如,对 example.org FROM domain.com 的请求是第三方请求。

注意

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
    其反向链接不是目标域的子域,反之亦然。例如,对 subdomain.example.org FROM example.org 的请求不是第三方请求
  2. Its Sec-Fetch-Site header is set to cross-site
    Sec-Fetch-Site 标头设置为 cross-site

Examples 例子

$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://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:

  • ||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://domain.com/icon.ico .
注意

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

$to

$to limits the rule scope to requests made to the specified domains and their subdomains. To add multiple domains to one rule, use the | character as a separator.
$to 将规则范围限制为向指定域及其子域发出的请求。若要将多个域添加到一个规则,请使用该 | 字符作为分隔符。

Examples 例子

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

$denyallow can not 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, Mac, and Android with CoreLibs v1.12 or later and AdGuard Browser Extension with TSUrlFilter v2.1.3 or later.
带有修 $to 饰符的 AdGuard for Windows、Mac 和 Android CoreLibs v1.12 或更高版本以及带有 TSUrlFilter v2.1.3 或更高版本的 AdGuard Browser Extension 支持带有修饰符的规则。

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

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 AdGuard Chromium 版AdGuard for Firefox AdGuard Firefox 版AdGuard iOS版AdGuard Safari版AdGuard 内容拦截器
$document
$font
$image
$media
$object
$other
$ping✅ *
$script
$stylesheet
$subdocument✅ *
$websocket✅ *✅ *
$xmlhttprequest
$webrtc 🚫 🚫 $webrtc
$object-subrequest 🚫 $object子请求 🚫
注意
  • ✅ — 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.
该规则对应于主框架文档请求,i.e. HTML在浏览器选项卡中加载的文档。它与 iframe 不匹配,这些 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 将 HTML 文档请求重定向到 example.com 空 html 文档。

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

  • ||example.com^$document,replace=/test1/test2/ replaces test1 with test2 in HTML document request to example.com.
    ||example.com^$document,replace=/test1/test2/ test1 替换为 test2 in HTML document request to example.com

注意

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 属性或属性引起的请求。

Compatibility 兼容性

AdGuard for Windows, Mac, and Android often cannot accurately detect navigator.sendBeacon(). Using $ping is not recommended in the filter lists that are supposed to be used by CoreLibs-based AdGuard products.
适用于 Windows、Mac 和 Android 的 AdGuard 通常无法准确检测 navigator.sendBeacon() .不建议在基于 CoreLibs 的 AdGuard 产品应该使用的过滤器列表中使用 $ping

Rules with $ping modifier are not supported by AdGuard for Safari and iOS.
AdGuard for Safari 和 iOS 不支持带 $ping 修饰符的规则。

$script

The rule corresponds to script requests, e.g. javascript, vbscript.
该规则对应于脚本请求,例如 javascript、vbscript。

$stylesheet

The rule corresponds to CSS files requests.
该规则对应于 CSS 文件请求。

注意

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

$subdocument

The rule corresponds to requests for built-in pages — HTML tags frame and iframe.
该规则对应于对内置页面的请求 — HTML 标记 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 及其所有子域的内置页面请求( frame и iframe ) ( example.com 及其子域)。
注意

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

Compatibility 兼容性

In AdGuard for Windows, Mac, and Android subdocuments are being detected by the Sec-Fetch-Dest header if it is present. Otherwise, some main pages may be treated as subdocuments.
在 AdGuard for Windows、Mac 和 Android 中,Sec-Fetch-Dest 标头正在检测子文档(如果存在)。否则,某些主页可能会被视为子文档。

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

$websocket

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

Compatibility 兼容性

$websocket modifier is supported in all AdGuard products except AdGuard Content Blocker. As for AdGuard for Safari and AdGuard for iOS, it's supported on devices with macOS Monterey (version 12) and iOS 16 or higher.
$websocket 除 AdGuard 内容拦截器外,所有 AdGuard 产品都支持修饰符。至于 AdGuard for Safari 和 AdGuard for iOS,它支持装有 macOS Monterey(版本 12)和 iOS 16 或更高版本的设备。

$xmlhttprequest

The rule applies only to ajax requests (requests sent via javascript object XMLHttpRequest).
该规则仅适用于 ajax 请求(通过 javascript 对象 XMLHttpRequest 发送的请求)。

注意

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

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.
适用于 Windows、Mac、Android 的 AdGuard 在过滤旧版浏览器时无法准确检测此类型,有时会将其检测为 $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 阻止 webRTC 连接到 example.com from example.org
  • @@*$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 AdGuard Chromium 版AdGuard for Firefox AdGuard Firefox 版AdGuard iOS版AdGuard Safari版AdGuard 内容拦截器
$content
$elemhide
$extension
$jsinject
$stealth
$urlblock✅ *✅ *
$genericblock✅ *✅ *
$generichide
$specifichide
注意
  • ✅ — 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 禁用 AT 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 禁用 at example.com 和所有子域的页面上的所有修饰规则。
注意

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

$extension

Disables specific userscripts or all userscripts for a given domain.
禁用给定域的特定用户脚本或所有用户脚本。

Syntax 语法

$extension[="userscript_name1"[|"userscript_name2"[|"userscript_name3"[...]]]]

userscript_name(i) stands for a specific userscript name to be disabled by the modifier. The modifier can contain any number of userscript names or none. In the latter case the modifier disables all the userscripts.
userscript_name(i) 表示要由修饰符禁用的特定用户脚本名称。修饰符可以包含任意数量的用户脚本名称,也可以不包含任何用户脚本名称。在后一种情况下,修饰符将禁用所有用户脚本。

Userscript names usually contain spaces or other special characters, which is why you should enclose the name in quotes. Both single (') and double (") ASCII quotes are supported. Multiple userscript names should be separated with a pipe (|). However, if a userscript name is a single word without any special characters, it can be used without quotes.
用户脚本名称通常包含空格或其他特殊字符,这就是为什么您应该将名称括在引号中的原因。支持单 ( ' ) 和双 ( " ) ASCII 引号。多个用户脚本名称应用管道 ( | ) 分隔。但是,如果用户脚本名称是没有任何特殊字符的单个单词,则可以不带引号使用。

You can also exclude a userscript by adding a ~ character before it. In this case, the userscript will not be disabled by the modifier.
您还可以通过在用户脚本前面添加字符 ~ 来排除用户脚本。在这种情况下,修改器不会禁用用户脚本。

$extension=~"userscript name"
注意

When excluding a userscript, you must place ~ outside the quotes.
排除用户脚本时,必须放在 ~ 引号之外。

If a userscript's name includes quotes ("), commas (,), or pipes (|), they must be escaped with a backslash (\).
如果用户脚本的名称包含引号 ( " )、逗号 ( , ) 或竖线 ( | ),则必须使用反斜杠 ( \ ) 对其进行转义。

$extension="userscript name\, with \"quote\""

Examples 例子

  • @@||example.com^$extension="AdGuard Assistant" disables 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'|'Popup Blocker' disables both AdGuard Assistant and Popup Blocker userscripts on example.com website.
    @@||example.com^$extension='AdGuard Assistant'|'Popup Blocker' 禁用 AdGuard Assistant Popup Blocker example.com 网站上的用户脚本。
  • @@||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"|~"Popup Blocker" disables all user scripts on example.com website, except AdGuard Assistant and Popup Blocker.
    @@||example.com^$extension=~"AdGuard Assistant"|~"Popup Blocker" 禁用 example.com 网站上的所有用户脚本,但 AdGuard AssistantPopup Blocker 除外。
  • @@||example.com^$extension no userscript will work on webpages on example.com.
    @@||example.com^$extension 没有 userscript 可以在 上的 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 修饰符的规则。
  • $extension modifier with specific userscript name is supported by AdGuard for Windows, Mac, and Android, running CoreLibs version 1.13 or later.
    $extension 运行 CoreLibs 版本 1.13 或更高版本的 Windows、Mac 和 Android 版 AdGuard 支持具有特定用户脚本名称的修饰符。

Rules with $extension modifier with specific userscript name are supported by AdGuard for Windows, Mac and Android with CoreLibs v1.13 or later.
$extension 带有特定用户脚本名称的 AdGuard 支持 CoreLibs v1.13 或更高版本的 AdGuard for Windows、Mac 和 Android。

$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 在 AT example.com 和所有子域的页面上禁用 JavaScript。

$stealth

Disables the Stealth Mode module for all corresponding pages and requests.
禁用所有相应页面和请求的隐身模式模块。

Syntax 语法

$stealth [= opt1 [| opt2 [| opt3 [...]]]]

opt(i) stand for certain Stealth Mode options disabled by the modifier. The modifier can contain any number of options (see below) or none. In the latter case the modifier disables all the Stealth Mode features.
opt(i) 代表某些被修改器禁用的隐身模式选项。修饰符可以包含任意数量的选项(见下文)或无选项。在后一种情况下,修改器会禁用所有隐身模式功能。

The list of the available modifier options:
可用修饰符选项列表:

Examples 例子

  • @@||example.com^$stealth disables Stealth Mode 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 Stealth Mode only for script requests to domain.com (and its subdomains) on example.com and all its subdomains.
    @@||domain.com^$script,stealth,domain=example.com 仅对 on 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 愚弄措施。
注意

Blocking cookies and removing tracking parameters is achieved by using rules with $cookie and $removeparam modifiers. Exception rules with only $stealth modifier will not do those things. If you want to completely disable all Stealth Mode features for a given domain, you need to include all three modifiers: @@||example.org^$stealth,removeparam,cookie
阻止 cookie 和删除跟踪参数是通过使用带有 $cookie$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 将被拒绝。
Compatibility 兼容性
  • Stealth Mode is available in AdGuard for Windows, Mac, and Android, and AdGuard Browser Extension. All other products will ignore the rules with $stealth modifier.
    隐身模式在 AdGuard for Windows、Mac 和 Android 以及 AdGuard Browser Extension 中可用。所有其他产品将忽略带有 $stealth 修饰符的规则。
  • Rules with $stealth modifier with specific options are supported by AdGuard for Windows, Mac, and Android with CoreLibs v1.10 or later.
    带有特定选项的 AdGuard for Windows、Mac 和 Android CoreLibs v1.10 或更高版本支持带有 $stealth 修饰符的规则。

$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 和所有子域发送的任何请求都不会被阻止。
Compatibility 兼容性

In AdGuard for iOS and AdGuard for Safari, rules with $urlblock work as $document exclusion — unblock everything.
在 AdGuard for iOS 和 AdGuard for Safari 中,将 $urlblock 工作作为排除的规则$document - 取消阻止所有内容。

Rules with $urlblock modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有 $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 禁用通用基本规则。
Compatibility 兼容性

In AdGuard for iOS and AdGuard for Safari, rules with $genericblock work as $document exclusion — unblock everything.
在 AdGuard for iOS 和 AdGuard for Safari 中,将 $genericblock 工作作为排除的规则$document - 取消阻止所有内容。

Rules with $genericblock modifier are not supported by AdGuard Content Blocker.
AdGuard 内容拦截器不支持带有 $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 子域的任何页面上禁用通用修饰规则。
注意

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 .
注意

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

注意

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

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 AdGuard Chromium 版AdGuard for Firefox AdGuard Firefox 版AdGuard iOS版AdGuard Safari版AdGuard 内容拦截器
$all
$badfilter
$cookie
$csp
$hls
$inline-font $inline字体
$inline-script $inline脚本
$jsonprune
$network
$permissions
$redirect
$redirect-rule $redirect规则
$referrerpolicy
$removeheader
$removeparam
$replace
noop
$empty 👎 👎 $empty
$mp4 👎 $mp 4 👎
注意
  • ✅ — fully supported ✅ — 完全支持
  • ✅ * — supported, but reliability may vary or limitations may occur; check the modifier description for more details
    ✅ * — 支持,但可靠性可能会有所不同或存在限制;查看修改器说明了解更多详情
  • ❌ — not supported ❌ — 不支持
  • 👎 — deprecated; still supported but will be removed in the future
    👎 — 已弃用;仍受支持,但将来会删除

$all

$all modifier is made of all content-types modifiers and $popup. E.g. rule ||example.org^$all is converting into rule:
$all 修饰符由所有内容类型修饰符和 $popup 组成。例如,规则 ||example.org^$all 正在转换为规则:

||example.org^$document,subdocument,font,image,media,object,other,ping,script,stylesheet,websocket,xmlhttprequest,popup

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

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.io 被禁用 for example.comexample.org by /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.* 被禁用 for example.comexample.org by /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 by /some$domain=example.com|~example.org,badfilter ,因为 $domain 修饰符的值包含否定的域
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 禁止显示或修改 Cookie and Set-Cookie 标头。

Multiple rules matching a single request
多个规则匹配单个请求

In case if multiple $cookie rules match a single request, we will apply each of them one by one.
如果多个 $cookie 规则与单个请求匹配,我们将逐个应用每个规则。

Syntax 语法

$cookie [= name[; maxAge = seconds [; sameSite = strategy ]]]

where: 哪里:

  • name — optional, string or regular expression to match cookie name.
    name — 可选的字符串或正则表达式以匹配 Cookie 名称。
  • seconds — number of seconds for current time to offset the expiration date of cookie.
    seconds — 当前时间的秒数,用于抵消 cookie 的到期日期。
  • strategy — string for Same-Site strategy to make cookie use.
    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 遇到请求中调用 NAMEexample.org cookie 时,它都会执行以下操作:

  • Set its expiration date to current time plus 3600 seconds
    将其到期日期设置为当前时间加 3600
  • Makes the cookie use Same-Site "lax" strategy.
    使 cookie 使用同站“宽松”策略。

Escaping special characters
转义特殊字符

If regular expression name is used for matching, two characters must be escaped: comma , and dollar sign $. Use backslash \ 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[a-z]/ 在任何地方阻止 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
  • @@||example.org^$cookie=/^_ga_/ unblocks every cookie that matches the regular expression
    @@||example.org^$cookie=/^_ga_/ 取消阻止与正则表达式匹配的每个 Cookie
Restrictions 限制

$cookie rules support three types of modifiers: $domain, $~domain, $important, $third-party, and $~third-party.
$cookie 规则支持三种类型的修饰符: $domain 、、 $~domain$important $third-party $~third-party 和 。

Compatibility 兼容性

Rules with $cookie modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard iOS 版和 Safari 版 AdGuard 不支持带 $cookie 修饰符的规则。

$csp

This modifier completely changes the rule behavior. If it is applied to a rule, the rule will not block the matching request. Response headers will be modified instead.
此修饰符完全更改了规则行为。如果将其应用于规则,则该规则不会阻止匹配请求。将改为修改响应标头。

信息

In order to use this type of rules, it is required to have the basic understanding of the Content Security Policy security layer.
为了使用此类规则,需要对内容安全策略安全层有基本的了解。

For the requests matching a $csp rule, we will strengthen response security policy by enhancing the content security policy, similar to the content security policy of the $csp modifier contents. $csp rules are applied independently from any other rule type. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
对于符合 $csp 规则的请求,我们将通过增强内容安全策略来加强响应安全策略,类似于 $csp 修饰符内容的内容安全策略。 $csp 规则独立于任何其他规则类型应用。只有文档级别的异常可以影响它(请参阅示例部分),但没有其他基本规则。

Multiple rules matching a single request
多个规则匹配单个请求

In case if multiple $csp rules match a single request, we will apply each of them.
如果多个 $csp 规则与单个请求匹配,我们将应用每个规则。

Syntax 语法

$csp value syntax is similar to the Content Security Policy header syntax.
$csp value 语法类似于内容安全策略标头语法。

$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 limited list 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 iOS 版和 AdGuard Safari 版不支持带 $csp 修饰符的规则。

$hls

$hls rules modify the response of a matching request. They are intended as a convenient way to remove segments from HLS playlists (RFC 8216).
$hls 规则修改匹配请求的响应。它们旨在作为从 HLS 播放列表中删除片段的便捷方法 (RFC 8216)。

注意

The word "segment" in this document means either a "Media Segment" or a "playlist" as part of a "Master Playlist": $hls rules do not distinguish between a "Master Playlist" and a "Media Playlist".
本文档中的“片段”一词是指“媒体片段”或作为“主播放列表”一部分的“播放列表”: $hls 规则不区分“主播放列表”和“媒体播放列表”。

Syntax 语法

  • ||example.org^$hls=urlpattern removes segments whose URL matches the URL 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 规则中的模式类似,但是,字符 /$ 必须 , 使用 \ inside 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 饰符值等于 text 来自匹配 ||example.org^ 的 URL 的响应的所有 $hls 规则。
提示

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

注意

When multiple $hls rules match the same request, their effect is cumulative.
当多个 $hls 规则与同一请求匹配时,其效果是累积的。

Examples 例子

  • ||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads removes all segments with the matching URL.
    ||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads 移除具有匹配 URL 的所有区段。
  • ||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i achieves more or less the same with a regular expression instead of a URL pattern.
    ||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i 使用正则表达式而不是 URL 模式实现或多或少相同的效果。
  • ||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t removes all segments which have the matching tag.
    ||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t 删除具有匹配标记的所有区段。

Anatomy of an HLS playlist
HLS 播放列表剖析

A quick summary of the specification:
规范的快速摘要:

  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
    代码可以应用于单个区段,即代码后的第一个网址行,也可以应用于代码后面的所有区段,直到具有相同名称的代码,或者整个播放列表

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 rrules 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 不能使用 rrules 删除它们,因为这些规则类型用于删除区段。如果您知道自己在做什么,则可以使用 $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 限制
  • $hls rules are only allowed in trusted filters.
    $hls 规则仅在受信任的筛选器中允许。
  • $hls rules are compatible with the modifiers $domain, $third-party, $app, $important, $match-case, and $xmlhttprequest only.
    $hls 规则与修饰符 $domain$third-party$app$important $match-case$xmlhttprequest 和 only 兼容。
  • $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.
    $hls 如果原始响应的大小超过 10 MB,则规则不适用。
Compatibility 兼容性

Rules with the $hls modifier are supported by AdGuard for Windows, Mac, and Android, running CoreLibs version 1.10 or later.
运行 CoreLibs 版本 1.10 或更高版本的 AdGuard for Windows、Mac 和 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 规则通过删除与修改后的 JSONPath 表达式匹配的 JSON 项来修改对匹配请求的响应。它们不会修改不是有效 JSON 文档的响应。

In AdGuard for Windows, Mac, and Android running 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.
由于规则解析的工作方式,字符 $, 必须用 \ inside 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/

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 $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 disable 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 饰符值等于 text 来自匹配 ||example.org^ 的 URL 的响应的所有 $jsonprune 规则。

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

注意

When multiple $jsonprune rules match the same request, they are sorted in lexicographical order, the first rule is applied to the original response, and each of the remaining rules is applied to the result of applying the previous one.
当多个 $jsonprune 规则与同一请求匹配时,它们将按字典顺序排序,第一个规则应用于原始响应,其余每个规则将应用于应用前一个规则的结果。

Examples 例子

  • ||example.org^$jsonprune=\$..[one\, "two three"] removes all occurrences of the keys "one" and "two three" anywhere in the JSON document.
    ||example.org^$jsonprune=\$..[one\, "two three"] 删除 JSON 文档中任意位置出现的所有键“one”和“two three”。
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)] 删除具有 ad_origin 密钥的所有 a 子项。
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 running CoreLibs v1.11 or later, JSONPath expressions may be used as keys in filter expressions.
在运行 CoreLibs v1.11 或更高版本的 AdGuard for Windows、Mac 和 Android 中,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")] 删除其所有子项 elems 具有可由 JSONPath 表达式 $.a.b.c 选择的属性。
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")] 删除其所有子项 elems ,其属性可由 JSONPath 表达 $.a.b.c 式选择,其值等于 "abc"
Input 输入
{
"elems": [
{
"a": {"b": {"c": 123}},
},
{
"a": {"b": {"c": "abc"}}
}
]
}
Output 输出
{
"elems": [
{
"a": {"b": {"c": 123}}
}
]
}
Restrictions 限制
  • $jsonprune rules are only compatible with these specific modifiers: $domain, $third-party, $app, $important, $match-case, and $xmlhttprequest.
    $jsonprune 规则仅与以下特定修饰符兼容: $domain$third-party$app$important $match-case $xmlhttprequest 和 。
  • $jsonprune rules do not apply if the size of the original response is more than 10 MB.
    $jsonprune 如果原始响应的大小超过 10 MB,则规则不适用。
Compatibility 兼容性

Rules with the $jsonprune modifier are supported by AdGuard for Windows, Mac, and Android, running CoreLibs version 1.10 or later.
运行 CoreLibs 版本 1.10 或更高版本的 AdGuard for Windows、Mac 和 Android 支持带有 $jsonprune 修饰符的规则。

$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 地址,您必须使用折叠的语法,例如 use [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.
从技术上讲,只有 AdGuard for Windows、Mac 和 Android 能够使用带有 $network 修饰符的规则。

$permissions

This modifier completely changes the rule behavior. If it is applied to a rule, the rule will not block the matching request. Response headers will be modified instead.
此修饰符完全更改了规则行为。如果将其应用于规则,则该规则不会阻止匹配请求。将改为修改响应标头。

信息

In order to use this type of rules, it is required to have a basic understanding of the Permissions Policy security layer.
为了使用此类规则,需要对权限策略安全层有基本的了解。

For the requests matching a $permissions rule, AdGuard strengthens response's permissions policy by adding an additional permission policy equal to the $permissions modifier contents. $permissions rules are applied independently from any other rule type. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
对于符合 $permissions 规则的请求,AdGuard 通过添加与 $permissions 修饰符内容相等的额外权限策略来加强响应的权限策略。 $permissions 规则独立于任何其他规则类型应用。只有文档级别的异常可以影响它(请参阅示例部分),但没有其他基本规则。

Multiple rules matching a single request.
多个规则匹配单个请求。

In case if multiple $permissions rules match a single request, AdGuard will apply each of them.
如果多个 $permissions 规则与单个请求匹配,AdGuard 将应用每个规则。

Syntax 语法

$permissions value syntax is similar to the Permissions-Policy header syntax with one exception: comma that separates several features MUST be escaped — see examples below. The list of the available directives is available here.
$permissions value 语法与 Permissions-Policy 标头语法类似,但有一个例外:必须对分隔多个功能的逗号进行转义 — 请参阅下面的示例。可用指令的列表可在此处找到。

$permissions value can be empty in the case of exception rules — see examples below.
$permissions 在异常规则的情况下,value 可以为空 — 请参阅以下示例。

Examples 例子

  • ||example.org^$permissions=autoplay=() disallows autoplay media requested through the HTMLMediaElement interface across example.org.
    ||example.org^$permissions=autoplay=() 不允许通过 HTMLMediaElement 界面请求的 example.org 自动播放媒体。
  • @@||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.
    @@||example.org/page/*$permissions=autoplay=() 在所有与规则模式匹配的页面上禁用 $permissions 修饰符完全匹配 autoplay=() 的所有规则。例如,上面的规则。
  • @@||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=() 不允许使用 Storage Access API 请求访问未分区的 Cookie,也不允许使用 example.orgexample.com 上的视频输入设备。
  • @@||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 规则。
Restrictions 限制
  1. Characters forbidden in the $permissions value: $
    $permissions 值中禁止的字符: $
  2. $permissions is compatible with three types of modifiers: $domain, $important, and $subdocument
    $permissions 兼容三种类型的修饰符: $domain$important$subdocument
Compatibility 兼容性

Rules with the $permissions modifier are supported by AdGuard for Windows, Mac, and Android, running CoreLibs version 1.11 or later.
运行 CoreLibs 版本 1.11 或更高版本的 Windows、Mac 和 Android 版 AdGuard 支持带有 $permissions 修饰符的规则。

$redirect

AdGuard is able to redirect web requests to a local "resource".
AdGuard 能够将 Web 请求重定向到本地“资源”。

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 $redirect=nooptext 将禁用所有规则,用于任何匹配 ||example.org^ 的请求。

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.
有关更多详细信息,请参阅规则优先级。

Compatibility 兼容性
  • Rules with $redirect modifier are not supported by AdGuard Content Blocker, AdGuard for iOS and AdGuard for Safari.
    AdGuard 内容拦截器、AdGuard iOS 版和 AdGuard Safari 版不支持带 $redirect 修饰符的规则。
  • $redirect in uBlock Origin supports specifying priority, e.g. $redirect=noopjs:42. AdGuard does not support it and instead just discards the priority postfix.
    $redirect 在 uBlock Origin 中支持指定优先级,例如 $redirect=noopjs:42 .AdGuard 不支持它,而只是丢弃优先级后缀。

$redirect-rule

This is basically an alias to $redirect since it has the same "redirection" values and the logic is almost similar. The difference is that $redirect-rule is applied only in the case when the target request is blocked by a different basic rule.
这基本上是一个别名, $redirect 因为它具有相同的“重定向”值并且逻辑几乎相似。区别在于,仅当目标请求被不同的基本规则阻止时, $redirect-rule 才适用。

Go to rules priorities for more details.
有关更多详细信息,请参阅规则优先级。

Negating $redirect-rule works exactly the same way as for regular $redirect rules. Even more than that, @@||example.org^$redirect will negate both $redirect and $redirect-rule rules.
否定 $redirect-rule 的工作方式与常规 $redirect 规则完全相同。不仅如此, @@||example.org^$redirect 还会否定两者 $redirect$redirect-rule 规则。

Examples 例子

||example.org/script.js
||example.org^$redirect-rule=noopjs

In this case, only requests to example.org/script.js will be "redirected" to noopjs. All other requests to example.org will be kept intact.
在这种情况下,只有 的 example.org/script.js 请求才会被“重定向”到 noopjs 。所有其他请求 example.org 将保持不变。

Compatibility 兼容性

Rules with $redirect-rule modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard iOS 版和 Safari 版 AdGuard 不支持带 $redirect-rule 修饰符的规则。

$referrerpolicy

These rules allow overriding of a page's referrer policy. Responses to matching requests will have all of their Referrer-Policy headers replaced with a single header with the value equal to the matching rule's modifier value. If the response carries an HTML document with a <meta name="referrer"... tag, the content attribute of the tag will also be replaced with the modifier value.
这些规则允许覆盖页面的引荐来源地政策。对匹配请求的响应将替换其 Referrer-Policy 所有标头,其值等于匹配规则的修饰符值的单个标头。如果响应携带带有 <meta name="referrer"... 标记的 HTML 文档,则标记的 content 属性也将替换为修饰符值。

An exception rule with a modifier value disables the blocking rule with the same modifier value. An exception rule without a modifier value disables all matched referrer-policy rules.
具有修饰符值的例外规则将禁用具有相同修饰符值的阻止规则。不带修饰符值的异常规则将禁用所有匹配的反向链接策略规则。

If a request matches multiple $referrerpolicy rules not disabled by exceptions, only one of them (it is not specified which one) is applied. $referrerpolicy rules without specified content-type modifiers apply to $document and $subdocument content types.
如果请求与多个未被异常禁用 $referrerpolicy 的规则匹配,则仅应用其中一个规则(未指定是哪一个规则)。 $referrerpolicy 没有指定内容类型修饰符的规则适用于 $document$subdocument 内容类型。

Examples 例子

  • ||example.com^$referrerpolicy=unsafe-url overrides the referrer policy for example.com with unsafe-url.
    ||example.com^$referrerpolicy=unsafe-url example.com 覆盖 with unsafe-url 的 referrer 策略。
  • @@||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, Mac, and Android, running CoreLibs version 1.12 or later.
运行 CoreLibs 版本 1.12 或更高版本的 Windows、Mac 和 Android 版 AdGuard 支持带有 $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 $removeheader=header 否定规则 对于任何请求匹配 ||example.org^

$removeheader rules can also be disabled by $document and $urlblock exception rules. But basic exception rules without modifiers will not do that. For example, @@||example.com^ will not disable $removeheader=p for requests to example.com, but @@||example.com^$urlblock will.
$removeheader 规则也可以由 $document 例外 $urlblock 规则禁用。但是没有修饰符的基本异常规则不会这样做。例如, @@||example.com^ $removeheader=p 不会禁用对 example.com 的请求,而是 @@||example.com^$urlblock 会。

注意

In case of multiple $removeheader rules matching a single request, we will apply each of them one by one.
如果多个 $removeheader 规则与单个请求匹配,我们将逐一应用每个规则。

Examples 例子

  • ||example.org^$removeheader=refresh removes Refresh header from all HTTP responses returned by example.org and its subdomains.
    ||example.org^$removeheader=refresh 从 及其 example.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 响应中删除 Refresh 标头, Location 以保存对 example.org/path/* 的请求,不会删除任何标头:

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

This type of rules can be used only 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, $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$app $important $match-case 、 和 内容类型修饰符(如 $script$stylesheet )兼容。具有任何其他修饰符的规则将被视为无效,将被丢弃。

Compatibility 兼容性

Rules with $removeheader modifier are supported by AdGuard for Windows, Mac, and Android, and AdGuard Browser Extension for Chrome, Firefox, and Edge.
适用于 Windows、Mac 和 Android 的 AdGuard 以及适用于 Chrome、Firefox 和 Edge 的 AdGuard 浏览器扩展支持带 $removeheader 修饰符的规则。

$removeparam

注意

$queryprune is an alias of $removeparam. Since $queryprune is deprecated, avoid using it and use $removeparam instead.
$queryprune 是 的 $removeparam 别名。由于 $queryprune 已弃用,请避免使用它并改用 $removeparam

Rules with $removeparam modifier are intended to strip query parameters from requests' URLs. Please note that such rules are only applied to GET, HEAD, OPTIONS, and sometimes POST requests.
带有 $removeparam 修饰符的规则旨在从请求的 URL 中剥离查询参数。请注意,此类规则仅适用于 、 HEADOPTIONS ,有时 POST 也适用于 GET 请求。

$removeparam rules that do not have any content type modifiers will match only requests where content type is document.
$removeparam 没有任何内容类型修饰符的规则将仅匹配内容类型为 document 的请求。

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 .
Compatibility 兼容性

Rules with $removeparam modifier are supported by AdGuard for Windows, Mac and, Android with CoreLibs v1.7 or later and AdGuard Browser Extension v3.6 or later.
带有 CoreLibs v1.7 或更高版本的 AdGuard for Windows、Mac 和 Android 版 AdGuard 浏览器扩展 v3.6 或更高版本的 AdGuard 支持带 $removeparam 修饰符的规则。

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: \,.
不要忘记 $ 在正则表达式中转义特殊字符,如 ,/ 。为此目的使用 \ 字符。例如,转义的逗号应如下所示: \, .

注意

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:
我们将尝试使用一个简单的经验法则自动检测和忽略未转义 $ - 如果这三个都为真,则它不是选项分隔符:

  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 $removeparam=param 否定规则 对于任何请求匹配 ||example.org^
  • @@||example.org^$removeparam=/regexp/ negates the rule with $removeparam=/regexp/ for any request matching ||example.org^.
    @@||example.org^$removeparam=/regexp/ $removeparam=/regexp/ 否定规则 对于任何请求匹配 ||example.org^

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 Click ID 将从所有请求中删除。但有一个例外:Google Click 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 会禁用。

Restrictions 限制
  • Rules with $removeparam modifier can be used only in trusted filters.
    带有 $removeparam 修饰符的规则只能在受信任的筛选器中使用。
  • $removeparam rules are compatible with basic modifiers, content-type modifiers, and with $important and $app modifiers. Rules with any other modifiers are considered invalid and will be discarded.
    $removeparam 规则与基本修饰符、内容类型修饰符以及 WITH $important$app 修饰符兼容。包含任何其他修饰符的规则将被视为无效,将被丢弃。
Compatibility 兼容性
  • Rules with $removeparam modifier are supported by AdGuard for Windows, Mac, and Android and AdGuard Browser Extension for Chrome, Firefox, and Edge.
    适用于 Windows、Mac 和 Android 的 AdGuard 以及适用于 Chrome、Firefox 和 Edge 的 AdGuard 浏览器扩展支持带 $removeparam 修饰符的规则。
  • $removeparam syntax for regular expressions is supported by AdGuard Browser Extension v4.0 and AdGuard for Windows, Mac, and Android, running CoreLibs version 1.8 or later.
    $removeparam 运行 CoreLibs 版本 1.8 或更高版本的 AdGuard 浏览器扩展 v4.0 和 AdGuard for Windows、Mac 和 Android 支持正则表达式语法。
  • POST request types are supported only by AdGuard for Windows, Mac, and Android with CoreLibs v1.10 or later.
    POST 只有 CoreLibs v1.10 或更高版本的 AdGuard for Windows、Mac 和 Android 版才支持请求类型。

$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 规则适用于任何文本响应,但不适用于二进制( mediaimage object 、 等)。
  • $replace rules do not apply if the size of the original response is more than 10 MB.
    $replace 如果原始响应的大小超过 10 MB,则规则不适用。
  • $replace rules have a higher priority than other basic rules (including exception rules). So if a request corresponds to 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>;
  • replacement\$1<\/VAST> where $ is escaped;
    replacement\$1<\/VAST> 逃逸的地方 $ ;
  • modifiersi for insensitive search.
    modifiersi 用于不敏感的搜索。

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!
    规则 2 对于匹配 ||example.org/page/ 的请求被禁用,但规则 1 仍然有效!

Disabling $replace rules
禁用 $replace 规则

  • @@||example.org^$replace will disable all $replace rules matching ||example.org^.
    @@||example.org^$replace 将禁用所有 $replace 匹配 ||example.org^ 的规则。
  • @@||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 将禁用源自页面的所有 $replace example.org 规则,包括页面本身。
Restrictions 限制

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

Compatibility 兼容性

Rules with $replace modifier are supported by AdGuard for Windows, Mac, and 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.
适用于 Windows、Mac 和 Android 的 AdGuard 以及适用于 Firefox 的 AdGuard 浏览器扩展支持带 $replace 修饰符的规则。此类规则在其他浏览器的扩展中不起作用,因为它们无法在网络级别修改内容。

noop

noop modifier does nothing and can be used solely to increase rules' readability. It consists of a sequence of underscore characters (_) of any length and can appear in a rule as many times 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^$empty 返回对所有 example.org 子域的所有请求的空响应。
Compatibility 兼容性

Rules with $empty modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
AdGuard 内容拦截器、AdGuard iOS 版和 Safari 版 AdGuard 不支持带 $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 iOS 版和 Safari 版 AdGuard 不支持带 $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, it depends on the filtering engine implementation which one will be selected.
当具有相同优先级的两个规则与同一请求匹配时,将选择哪一个取决于筛选引擎实现。

信息

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,规则优先级的概念变得越来越重要,因为需要将现有规则转换为声明性 NetRequest 规则。

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.
    适用于 iOS、Safari 的 AdGuard 和 AdGuard 内容拦截器依赖于浏览器实现,它们无法遵循此处指定的规则。
注意

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 的优先级

  • $app with negated applications using ~,
    $app 对于否定的应用程序,使用 ~
  • $denyallow,
  • $domain with negated domains using ~,
    $domain 对于否定的域,使用 ~
  • $match-case,
  • $method with negated methods using ~,
    $method 用否定的方法使用 ~
  • $third-party,
  • $to,
  • restricted content-types with ~.
    受限制的内容类型。 ~

When dealing with a negated domain, app, method, or content-type, we add 1 point for the existence of the modifier itself, regardless of the quantity of negated domains or content-types. This is because the rule's scope is already infinitely broad.
在处理否定的域、应用、方法或内容类型时,无论否定域或内容类型的数量如何,我们都会为修饰符本身的存在添加 1 分。这是因为该规则的范围已经无限广泛。

Put simply, by prohibiting multiple domains, content-types, methods or apps, the scope of the rule becomes only minimally smaller.
简而言之,通过禁止多个域、内容类型、方法或应用程序,规则的范围只会变得很小。

Defined content-type modifiers, defined methods, defined headers, $all, $popup, specific exceptions
定义的内容类型修饰符、定义的方法、定义的标头、$all、$popup、特定异常

All allowed 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 add 指定的域或通过 $app add 100 + 100 / N 指定的应用程序,其中 N 是修饰符值的个数,例如: ||example.com^$domain=example.com|example.org|example.net will add 100 + 100 / 3 = 134.3 = 135||example.com^$app=org.example.app1|org.example.app2 will add 100 + 100 / 2 = 151||example.com^$domain=example.com,app=org.example.app1|org.example.app2 will add 100 + 100/1 ($domain part) 和 100 + 100/2 ($app part),合计 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.
作为正则表达式或 tld 的修饰符值将被解释为表单 example.com 的普通条目并逐个计数,例如: ||example.com^$domain=example.* will add 100 + 100 / 1 = 200||example.com^$domain=example.*|adguard.* will add 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.
其他修饰符应该对请求执行额外的后处理或预处理,但不会向规则优先级添加任何内容。

注意

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 中的$redirect: 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 + 允许的内容类型,类别 2: 1 + 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 + 允许的域,类别 3: 1 + 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 + 允许的两种内容类型(文档和子文档),类别 2: 1 + 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 + 拒绝,类别 1: 1 + (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 AdGuard Chromium 版AdGuard for Firefox AdGuard Firefox 版AdGuard iOS版AdGuard Safari版AdGuard 内容拦截器
Element hiding 元素隐藏
CSS rules CSS 规则
Extended CSS 扩展 CSS
HTML filtering HTML 过滤
JavaScript
Scriptlets
注意
  • ✅ — fully supported ✅ — 完全支持
  • ❌ — not supported ❌ — 不支持

Cosmetic rules 外观规则

信息

Work with non-basic rules requires the basic knowledge of HTML and CSS. So, if you want to learn how to make such rules, we recommend to get acquainted with this documentation.
使用非基本规则需要 HTML 和 CSS 的基本知识。因此,如果您想学习如何制定此类规则,我们建议您熟悉此文档。

Element hiding rules 元素隐藏规则

Element hiding rules are used to hide the elements of web pages. It is similar to applying { display: none; } style to selected element.
元素隐藏规则用于隐藏网页的元素。它类似于将样式应用于 { display: none; } 所选元素。

Element hiding rules may operate differently depending on the platform.
元素隐藏规则的运行方式可能因平台而异。

Syntax 语法

   rule = [domains] "##" selector
domains = [domain0, domain1[, ...[, domainN]]]
  • selectorCSS selector, defines the elements to be hidden.
    selector — CSS 选择器,定义要隐藏的元素。
  • domains — domain restriction for the rule.
    domains — 规则的域限制。

If you want to limit the rule application area to certain domains, just enter them separated with commas. For example: example.org,example.com##selector.
如果要将规则应用区域限制为某些域,只需输入以逗号分隔的域即可。例如: example.org,example.com##selector .

This rule will be also applied to all subdomains of example.org and example.com.
此规则也将应用于 example.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 .

注意

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 — 隐藏 A div 和 AT example.comtextad 以及所有子域。
  • 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 — 隐藏属性 idadblock 于 at example.com 的元素和 example.org 所有子域。
  • ~example.com##.textad — hides an element with the class textad at all domains, except example.com and its subdomains.
    ~example.com##.textad — 在所有域(及其子域除外 example.com )中隐藏具有该类 textad 的元素。

限制

Safari does not support both permitted and restricted 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.
    selector — CSS 选择器,用于定义我们想要应用样式的元素。
  • domains — domain restriction for the rule. Same principles as in element hiding rules.
    domains — 规则的域限制。与元素隐藏规则中的原则相同。
  • style — CSS style, that we want to apply to selected elements.
    style — CSS 样式,我们希望将其应用于选定的元素。

Examples 例子

example.com#$#body { background-color: #333!important; }

This rule will apply a style background-color: #333!important; to the body element at example.com and all subdomains.
此规则会将样式 background-color: #333!important; 应用于 at 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 元素自己的表示形式(样式、文本内容等)或与其他元素的关系来匹配选择器。还有机会应用具有非标准 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"]) — 此规则阻止包含与属性 [target="_blank"][rel="nofollow"] 具有链接的子节点的所有 div 元素。该规则仅适用于 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 设置为包含单词 cookies 的所有 h3 元素。该规则仅适用于 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.
您可以使用规则标记,使用 ExtendedCss 库应用标准 CSS 选择器 #?# ,例如 #?#div.banner .

Learn more about how to debug extended selectors.
详细了解如何调试扩展选择器。

注意

Some pseudo-classes do not require selector before it. Still adding the universal selector * makes an extended selector easier to read, even though it has no effect on the matching behavior. So selector #block :has(> .inner) works exactly like #block *:has(> .inner) but 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
ExtendedCss 限制

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

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

注意

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() ,即内部没有其他扩展选择器。要强制应用 ExtendedCss :has() 规则,请显式使用 #?# / #$?# 标记。

Compatibility with other pseudo-classes
与其他伪类的兼容性

Synonyms :-abp-has() is supported by ExtendedCss for better compatibility.
ExtendedCss 支持同义词 :-abp-has() ,以获得更好的兼容性。

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.
本机实现不允许 :scope:has() 参数 ( [1], [2]) 中使用任何 inside。尽管如此,筛选器列表中还是有一些这样的规则: 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) 选择包含元素的所有 div 元素,该元素具有以下 banner 类:

<!-- 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) 选择 banner 紧跟在 div 和 之后的 class 元素前面的所有 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) 选择类元素前面 banner 的所有 div 元素,该元素紧跟 但不一定紧跟在 后面 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) 选择同时 span 包含 element 和 banner class 元素的所有 div 元素:

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

注意

The :contains() pseudo-class uses the textContent element property for matching, not the innerHTML.
:contains() 伪类使用 textContent element 属性进行匹配,而不是 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)
注意

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.
仅选择 with 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 — required,要检查元素的 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}/) .

注意

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 filters 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)