详细说明：
如何编写 Adblock Plus 的过滤器规则.pdf
译自：https://help.eyeo.com/en/adblockplus/how-to-write-filters
pan.baidu.com/s/1hnotuYHN_z_8od4b5BYBMA 密 6fsu译者注:以下来自 Adquard特殊字符的介绍
一通配符.可用于表示“任意字符集"。也可以是空字符串或任何长度的字符串
—一匹配地址的开头。使用此字符,你不必在地址掩码中指定特定的协议和子域。意思足,‖即
刻代表了http://*.,https://*,ws://*,wss//*
·∧一作分隔符的字符标记。分隔符可以是任意字符,但不能是字母,数字或以下字符之
。在此示例中,分隔符以粗体显示http://example.com/?t=1&t2=t3地址的末尾也可以用
分隔符。
—指向地址开头或结尾的指针。该值取决于地址掩码中字符的位置( The value depends on the
characterplacementinthemask)例如,过滤词sW对应于http://example.com/annoyingflas
h.swf但不对应于http://example.com/swf/index.htmlhttp://example.org对应于httpexample
org,但不对应于ht//domain.com?url-htt//example.org。
注释 Comments
任何以感叹号(!)开头的规则都被视为注释。 Adblock plus会忽略此规则以实际阻止,因此在评论中
编写您想要的任何内容都是安全的。您可以在过滤器上方放置注释规则来描述其目的或功能,或者放置
注释,说明您的作者身份(大多数过滤器列表作者都这样做)。
高级特性 Advanced features
指定过滤器参数 Specifying filter options
Adblock plus允许指派多个选项来变更过滤器的行为。这些选项应写在过滤器末尾的美元符号($)后,并
用逗号()分隔。
举例:/ads/* Script, match-Case
Adblock plus允许你指定一
这里,/ads/表示实际的过滤词, script和 match-case是过滤词的参数选项.目前支持的有
过滤类型选项 Type options
These determine which types of elements a filter can block (or whitelist in case of an exception ru
e). Multiple type options can be specified to indicate that the filter should be applied to several ty
pes of elements. Possible types include
这些决定过滤器可以阻止哪些类型元素(或属于例外规则的白名单)。可以指派多个类型选项,以指示
过滤器作用于多个类型的元素。可能的类型包括
script-通过 HTML script tag导入的外部 scripts
· Image-通过 HTML img tag导入的常规 Images
stylesheet-外部CSS样式文件
object-浏览器插入的控件句柄,如 Flash java
xmlhttpreQuest-使用XmlHttpreQueStobject或fetch0AP产生的请求
subdocument-嵌入式贞面,通常包含HTML内联棰架( iframe
ping-通过 navigator.sendBeacon发起的请求(需要 Adblock plus2,7.1以上版本
websocket-通过 Web Socket object对象发起的请求
Webrtc-通过 RTCPeerConnection instances实例接到 CE servers的连接(适用于 Chrome和Oper
a的 Adblock plus1.133或更高版本,适用于 Firefox的30或更高版本)
document-页面本身(仅让例外规则 exception rules被应用到该页面)
elemhide-仅用于例外规则。与参数 document类似,在例外规则的方式,取消隐藏某个页面元
素的规则(需 Adblock Plus1.2及以上版木)(译者注:原链接失效,用 adguard的解释代替。取
消任何页面上的CSS的装饰规则。举例
example.com/Selemhide
example. orgtittselector
cosmetic rules的含义
generichide-仅适用于例外规则,类似于 elemhide但仅关闭页面上的装饰元素 cosmetic rules隐
藏规则(译者注:说白了就是stNe装饰器元紊)。用于屏蔽在页面中使用的 global element rules
全局元素规则
译者注:引用adguard的例子|example.com^generichide
genericblock-for exception rules only, just like generichide but turns off generic blocking rules
(Adblock Plus 2.6. 12 or higher is required)
针对例外规则中使用。跟 gencrichide类似,但 gencricblock会关闭 generic blocking rules的使
用,来阻止全局的 blocking rules用到此页面上。(需 Adblock plus1.2及以上版本)
译者注:引用adguard的例子|example.com^$genericblock
· popup-指在新标签页或者新窗口中打开的页面。默认情况下pop-ups不会被阻止,除非$poup
选项被指派。
·font-外部字体文件
media_像音乐视频的常规媒体文件
· other-以上列表中没有被提到的请求类型
match-case-确保应用到页面请求的过滤词大小写敏感。过滤词*/ BannerAd. aⅰf$ match-case阻
止http://example.com/bannerad.g但不阻止http://example.com/bannerad.g
nverse type options类型选项取反
指派过滤器的中(请求)哪些类型不被应用到。可能的取反类型包括~ script,- rImage,- stylesheet,-obj
ect,-xmihttprequest,-subdocument,-ping,-websocket,-webrtc,-document,-elemhide,-other
Restriction to third- party/ first- party requests对第三方/第一方请求的限制
如果 third- party选项被指派,则过滤器将仅应用于来自与当前查看页面不同来源的请求。同样, third-p
arty将过滤词作用于来自与当前查看页面相同来源的请求。
Domain restrictions域名限制
optiondomain=example.com意味着过滤器将作用于来自example.com域名的页面。多个域名使用|分
隔符。对于选项domain=examplecomexample.net,过滤词将作用于example.com或examp|enet域名
的页面.如果域名名称使用~做前缀,则过滤词将不会被用来自这些域名的页面。例如 domain=- examp
ecom意味着过滤词将被用于域名 example. con以外的任意域名。选项 domain= example. com-foo
example:com限制过滤词仅作用于example.com域名,但排除foo.example.com子域名。
Sitekey restrictions限制 Sitekey
选项 sitekey= abcdsitekeydcba
表示该过滤器仅应用提供密钥的页面。页面签署生成的 sitekey用来页面验证与过滤器中的 sitekey内容
(不包过=符号)是相同的。
多个 sitekeys可通过丨符号区格。例如,选项 sitekey= abcdsitekeydcba bcdesitekeyedcb仅允许过滤词用
在提供相同 sitekey为 abcdsitekeydcba或 bcdesitekeyedcb的页面上。这点与 domain restrictions类似,
但仅用在多个单个过滤词要作用于一大堆域名的场景。
Note: Sitekey restrictions Th s modifications on the server-side
内容安全机制 Content Security Policies
译者注∷內容安全策略( Content Security Policy)是一种声明的安全机制,可以让网站运营者能够控制遵
循CSP的用户代理(通常是浏览器)的行为。通过控制要启用哪些功能,以及从哪里下载内容,可以减少
网站的攻击面。CSP的主要目的是防御跨站点脚本( cross- ste scripting,×SS)攻击。例如,CSP可以完全
禁止内联的 JavaScript,并且控制外部代码从哪里加载。它也可以禁止动态代码执行。禁用了所有的攻击
源,ⅩSS攻击变得更加困难。CSP由Moz训la开发,曾经有几年试验过概念,一开始称为内容限制( conte
nt restriction),后来改称为内容安全簧略。2012年11月CsP1.0成为W3C的候选议案。网站通过设置
Content- Security- Policy响应头启用所需的CSP策略。
选项csp= script-src:'none'导致 script-sic:mone这- Content Security Policy被注入到与该过滤词
相匹配的HTP响应头中(假定带着相同选项的例外规则未匹配,且 document对象未在白名单中)
Content Security Policy script-src:'none'阳止 document对象中所有的 scripts,包括内联使用的。通
常避免该选项,除非被作用最后的规避广告手段。( Adblock plus31 or higher is required.)。
限制内部资源的请求 Redirecting requests to internal resources
write= option可以在不产生错误的情况下,让∪RLs被重写(或重定向请求)到一个内部的资源。通
过名称或者abp- resource:做前缀来标识内部资源。例如$ rewrite=abp- resource: blank-js则发送空白
的Js脚本.( Adblock plus3.5 or higher required.)
可标识的内部资源有
bank-text-空白文本
bank-cSs-空白的样式表
·bank-js-空白的JS脚本
bank-htm|-空白的HTML文栏
· blank-mp3-持续0.1静默的MP3音频文件
1×1- transparent-gf-1X1像素透明的GF图像
2x2- transparent-png-2x2像素透明的PNG图像
·3x2 ransparent-png-3X2像素透明的PNG图像
·32×32- transparent-png-32×32像素透明的PNG图像e
狳以上之外的任何参数选项将使得该过滤词不发挥作用,使得请求通过。 make the filter have no effec
t and let the request pass through
使用正则表达式 Using regular expressions
AdblockκPus支持在过滤词中使用政策表达式。例如,过滤词中的/ banner\d+/匹配的是 banner123和
banner321而不是 banners.我们建议务必查看 Mozilla's documentation on regular expressions来学习
使用如何来撰写正则表达式。
注意:出于性能原因,我们建议尽可能避免使用正则表达式。
特殊的注释 Special comments
Special comments only have an effect in downloaded filter lists, not in custom filters. They can set
a number of parameters for the filter list
特殊注释仅对下载的过滤器列表有效(译者注:如 Easy Chinalist),而对自定义过滤器无效。他们可以为
过滤器列表设置许多参数
Homepage:hto/ example:com/-此注释确定将哪个网页链接作为过滤器列表的主页
·! Title: Foolish-此注释为过滤器列表设置了固定的标题。如果存在此注释,则用户不再能够更改
标题。
Expires: 5 days- This comment sets the update interval for the filter list. The value can be
given in days (e.g. 5 days) or hours (e.g. 8 hours). Any value between 1 hour and 14 days
s possible. Note that the update will not necessarily happen after this time interval. The actu
al update time is slightly randomized and depends on some additional factors to reduce ser
ver load
用来设置过滤器列表的吏新间隔。该值以天(例如5天)或小时(例如8小时)为单位给出。1
小时到14天之间的任何值都是可以的。请注意,大于此时间间隔不一定会进行更新。实际更新
时的时间会稍微随机化,并取决于一些其他因素以减少服务器负载
! Redirect:htp:/ example:com/isxt-此注释表明过滤器列表已移至新的下载地址。 Adblock p
us会忽略该注释以外的任何文件内容,并立即尝试从新地址下载。如果成功,则在设置中更新过
滤器列表的地址。如果新地址与当前地址相同,则忽略此注释,这意味着它可用于强制执行过滤
器列表的“规范”地址
Version: 1234- this comment defines a numerica version of the filter list this version nu
mber is displayed in issue reports and can be used to verify that the report refers to the cu
rrent version of the filter list定义了过滤器列表的数字版本。列表的版本号显示在问题报告中
可用于追溯当前使用列表中出现问题列表的版本号。
元素隐藏 Element hiding
基本规则 Basic rules
不幸的是,有些广告不能立即被阻止。这是因为它们是作为文本嵌入在网页本身中的。如果您查看网
页的源代码,则可能会看到这样的内容
Cheapest tofu, only here and now!
Only here you get the best tofu!
You'll need to download the webpage in order to download the advertisements. After the webpage
is downloaded, you can hide the advertisement(s) that you don't want to see
您需要下载页面才能下载广告。下载页面后,您才可以隐藏不想看的广告,你肯定不想这样。
The rule ##. textad hides any such element. Here ##f marks an element hiding rule while the rest is a
selector identifying the elements that need to be hidden. You can hide elements by their ID attrib
ute (similarly, ###tsponsorad hides the second advertisement) and by their name(e.g##textad for th
e third advertisement
上面的示例广告包含在cass属性为 tested的页面元素内。规则# extal可隐藏任何此类元素。这
里#标识了这是一个元素隐藏规则,其余规则是标识需要隐藏的元素的选择器
将规则限制到某些域 Limiting rules to certain domains
Typically, you may want to hide a specific ad on one site, but don't want your rule to be applied
to another site
通常,您可能希望在一个网站上隐藏特定的广告,但不希望将规则应用于另一网站。例如规则## spons
or可能会在某些站点上隐藏有效的代码。除非你写成 example. Com#4. sponso,它将作用于htbp//exam
precom/和ht/somethingexample.com,但不会在htp∥/example.org/生效.还可以通过简单地用
逗号分隔来指定多个域
domain 1 example, domain2. example, domain3. exampletttt sponsor
如果域名名称有前缀符-,即这条过滤词不作用于这些域名的页面。例如-example.com#sponsor不作
用于example.com之外的任何域名的页面。但是'example.com'andexample.com,~foo.example.Com#
sponsor这些规则将用于"example.com”域名,出来"foo.example.com”子域名.(译者注:原文拗口。
简意是:域名前的~符号,仅对域名作用,不是对~之后的整个规则内容作用)
注意:由于隐藏元素的实现方式,您需要使用完整域名名称。您不能使用部分网址的形式,也不能使用
domain替换 domain. example, domain test
属性选择器 Attribute selectors
些广告对你来说不简单一他们的文字广告使用D而不是一个cass类属性。你可以使用其他属性去隐
藏他们,例如 example# Ftablelwidth="80%"]将 width属性设置为80%。如果你不想指派完整的属性
值,例如# div[title*"ad将隐藏标题属性含有"adv"字符串的所有dⅳ元素。你也可以检查某属性的
开头或末尾,如#dⅳ[te^="adv"[tte$s"ert"将隐藏标题以"adv"开头,并以"ert"为结尾的cⅳ元
素。如你所见,你也可以使用多重条件— table[width="80%" bgcolor=" white"]会与 bgcolor属性为
白, width属性只有80%样式的表格匹配。
高级选择符 Advanced selectors
常理来说,任意浏览器支持的CSS选择器都可以用作 element元素的隐藏。例如过滤词## header+
将隐藏所有内含CaSs为" aheaded"内容的dv元素。你能在W3 s cSS selectors documentation中
见到完整的CSS选择器列表。请记住,浏览器处理基于cass属性的选择器比基于|D的速度要慢
注意:建议高级用户使用此功能。您会对使用CSS选择器感到满意。如果您使用CSS语法无效, Adblo
ck Plus将屏蔽该条锖误的CSS过滤词。
扩展的CSs选择器(仅限于 Adblock plus- specific) Extended CSS selectors( Adblock plus- specific)
有时,标准CSS选择器的功能不足以隐藏广告。对于这些情况,我们添加了一些新的选择器,即
- abp-haso
- abp-containso
abp- properties()(需在 Chrome and Opera中使用 Adblock Plus1.13.3或更高版本)
在编写使用这些扩展选择器的元素隐藏过滤词时,务必使用#?#syntax,例如example.com#?selector。
不过,这样做会对性能产生影响,因此应谨慎使用,并确保这些过滤词限定于尽可能少的域名和元素,这
点必须牢记
bp-haso
选择器:abp-has( selector)选择元素基于他们包含的内容。例如:-abp-has(>d> aadvertiser)命中
的元素包含内容有:一个方向符( direct descendant)做起始,一个含有一带有 css class名为adv
eraser的标签。括号甲面的选择器与元素作用范围相关,可以在-abp-has0括号里面使用任意的csS
伪-选择器:来确定是否进行选择。
注意:使用example.com#?#;-abp-has(sponsored)这样的过滤词将隐藏所有的页面,因为dss(sponso
red)也会出现在的一些地方。所以简单的添加>或+即可(译注:与上文 adheader类似
举例:假如往htos:/helpeyeo.com/en/adblockplus/how-to-write-filters添加过滤词eyeo.com#?#:-abp
-has(code),然后硬刷新(泽注:ctrl+F5),则所有的一切将被阻挡。这是因为包含了。
可修改过滤词为 eyed con#?#:-abp-has(>code)来修复这个问题。硬刷新后,仅的父元素被阻
止
: -abp-containso
选择器-abp- contains(tex):基于元素的文本内容来选择元素。例如选择器 div sidebar>span:-abp-co
ntains( Advertisement)命中的是包含 Advertisement"词汇,且 class类为 sidebar的。实践中,你
想要与a:-abp-has0联合使用来命中包含广告abe的外部容器,如 divsidebar>dv:-abp- has(span:-a
bp-contains(Advertisement
举例:假如往https;/help.eyeo.com/en/adblockplus/how-to-wrte-filters添加过滤词eyeo.cm#?#:-abp
contains( filters并且硬刷新,则没有任何改变。假如你改变过滤词为 eyes. com#?#iv-abp- contains(ft
ers且硬刷新,则由于页面中含有词汇 filters”的关系, divouter(容纳了页面的中间段落)会被
阻止。修改过滤词为eyeo.com#?#article-heading:-abp-contains(ters)可修正它。硬刷新后可看到每
篇文章的标题被隐藏。
abp propertieso
abp- properties( properties)选择器,会基于样式表来选择元素。例如:abp- properties(wdth;30px; heigh
t:250p×;)在样式表中选择与CSS规则对应的元素,该规则将wdh和 height分别设置为300px和250p
X。厲性名称区分大小写。此外,可使用通配符,这样-abp- properties(wdth* px; height:250px)将匹配
宽度wdth不限,高度固定为250pes样式的元素。
你也可以使用正则表达式,用""在属性表达式两头包起来。例如,:-abp- properties(wdth:30[2-8]px;h
eight:250p×/)匹配 widths302-308pies高度为250pel样式的元素。
Note: The old syntax for the CSS property filters is deprecated and will be automatically converted t
o the new format. The syntax to select the style properties remains the same
注意:过滤CSS属性旧的语法已被弃用,并将自动转换为新格式。
Note: When using the background-color property, use the rgb notation. For example, instead of
abp-properties(background-color: #3D9C4F ) use: -abp-properties(background-color: rgb(61, 156, 7
9)
注意:当使用 background-coor属性时,请使用rgb表示法。例如,使用use:-abp- properties( backgr
ound-color: rgb(61, 156, 79))43: -abp-properties(background-color: #3D9C4 F
举例:[-abp- properties=wdth:300 px; height:250px;转换成:-abp- properties(width:300x; height:250p
)。;-abp- properties()也可通过检查伪元素样式表中的属性来选择元素。像: before and: after。例
如,:-abp- properties( content: Advertisement),若具有 before或:aftr伪元素属性对应的元素含有A
dvertisement字符串,则该元素将被命中。
例外规则 Exception rules
例外规则可解除作用在特定域名上作用的过滤规则。这对过滤规则作者的筛选非常有用,因订阋获得规
则集往往从另一个规则集中扩展而来,且无法修改。举个例子,使用例外规则过滤词example.com并
# textad可以屏蔽作用在 example. com上的##, textad过滤词。两个过滤词联合使用,相当于~ exampl
ecom## textad的作用。建议仅在无法更改过于宽泛的元素隐藏规则时才使用例外规则。此外,最好在
过滤词上加入域名做规则限制。这个例外规则也会应用到 advanced pseudo- selector rules.
举例:如果往https:/help.eyeo.com/en/adblockplus/hoW-to-Wrte-fte添加过滤词##asideinfo,过滤
词eye.com##aside将不会被加入到白名单中。如果该网址添加的过滤词有##aside,则eyeo.com#
#asideinfo也不会被加至白名单中。过滤词必须完全相同,即eyeo.com##asideinfo(解除#asidein
fo的屏蔽)。
通用/定过滤器 Generic/ Specific filters
使用$ generichide和$ genericblock过滤器选项,则通用过滤器和特定过滤器之间的区别变待很重要。
如果过滤词(过滤器)匹配一个或多个域,或者匹配站点密钥,则我们将其归类为特定过滤器。如果过
滤器未指定任何域(或仅指定例外的域),也没有 sitekey,则将其视为通用过滤器。例如, example.C
om#,tested是一个特定的过滤器,而#textad和-example.com#etad都是通用的
注意:使用阻止规则( blocking rules)时,必须在$ domain选项下指定域,以将其祝为特定域。例如,
example:com∧被认为是诵用的,而/ads/*$ domain= example. con是限定于站点的。
在服务器上实现站点密钥 Implementing a sitekey on the server
要使用“站点密钥限制过滤器'( sitekey- restricted filter,网页需要返回base64编码的公共密钥版本以及可
由Adblockplu验证的签名。这意味着要将它们包含在HTTP响应标头(X-Adblock-Key:abcdpublickey
dcba_ abcdsignaturedcba)和页面 document0)的 root tag根标签中。
你必须创建一个私有RSA密钥(最好是512位,以保持较低的传输量),然后创建一个DER编码的 publi
C密钥。用于创建签名的数据是由NUL字符0"分隔级联呈现的请求变量(即URl,host, and user age
nt)o153a,/indEx.html?q=foo\oWww.example.com\omozilla/5.0(X11;Ubuntu;Linuxx8664:rv:30.0)
Gecko/20100101 firefox/ 30.0
要为该字符串生成签名,请使用 OpenSsL默认设置下的签名算法SEC_OD| SO SHA WITH RSA S|GNAT
UREO。
