过程式修饰规则

返回“静态过滤规则语法”

---

过程式（procedural）修饰过滤的概念是从 uBlock Origin（“uBO”）1.8.0 版本开始引入的。

过程式修饰过滤首次实现是在被修订为允许链接/递归使用过程式操作符的 1.11.0+ 版本。抛开常识，它在可链接（chained）的操作符数量，或可递归的层级方面没有任何限制，但 1.17.5rc1 之前的版本不支持在过程式选择符后面链接原生的 CSS 选择符。要提醒的是，请仅在普通 CSS 选择符无法解决问题的情况下使用过程式修饰规则。

普通、标准的修饰规则是 声明式 (declairative) 的，即作为一条 CSS 规则内的选择符来使用，并且完全通过 style 标签的元素被各浏览器处理。

过程式 表示 javascript 代码是用于查找必须被隐藏的 DOM 元素。一条过程式修饰规则会使用修饰规则 操作符 来告诉 uBO 如何查找或筛选 DOM 元素，以便找到目标 DOM 元素。

重要说明： 过程式修饰规则始终必须是专用的，即必须附带所生效的站点主机名作为前缀。如果一条过程式修饰规则是通用的，即在任何网站均生效，则 uBO 会忽略这条规则。举例来说，一条好规则必须是专用的，比如这样：example.com##body > div:has-text(Sponsored)；一条坏规则是因为它是通用的，比如这样：##body > div:has-text(Sponsored)。而元素选择器在创建修饰规则的时候始终会自动添加主机名作为前缀以确保规则是专用的。

高效的过程式修饰规则（或任何修饰规则）的定义是其作用结果只会访问最少的节点集合。元素选择器的输入框会显示与当前规则匹配的元素数量。元素选择器只考虑第一个换行符之前所输入的文本，其余部分则保持不变。你可以利用这个功能拆分你的规则来找到规则前半部分节点集合的数量：只有具有最少数量节点集合的修饰规则才是最高效的。

修饰规则操作符

subject:has(arg)

_{这个操作符是 uBO 1.15.0 中 :if(...) 出现语义上变动，两者类似}

• 描述：选择 subject 元素，当且仅当满足在 subject 元素的上下文（context）里对 arg 进行估值（evaluate）后返回一个或多个元素这个条件。
• 是否可链接（Chainable）：是。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• arg：可以是在 subject 元素的上下文中估值了的有效的普通 CSS 选择符或过程式修饰规则。
• 示例：
  • mobile.twitter.com##main [role="region"] > [role="grid"] > [role="rowgroup"] [role="row"]:has(div:last-of-type span:has-text(/^Promoted by/))
  • strikeout.me##body > div:has(img[alt="AdBlock Alert"])
  • yandex.ru##.serp-item:has(:scope > .organic > .organic__subtitle > .label_color_yellow) - :scope 强制要求 .organic 在 .serp-item 内部匹配 ^1,2
  • strdef.world##div[style]:has(> a[href="http://www.streamdefence.com/index.php"]) - > 强制要求 a 必须是 div 的直接子孙节点

这个 :has(arg) 操作符实际上是 CSS4 计划实现的伪类，但现阶段还不被任何浏览器支持。与其他浏览器厂商等待提供支持不同的是，uBO 现在就以过程式操作符的形式提供了对 :has(arg) 的支持。

subject:has-text(needle)

• 描述：选择 subject 元素，当且仅当满足 subject 元素内包含 needle 文本这个条件。
• 是否可链接：是。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• needle：必须是可找到的文本或正则表达式。如果是正则表达式，你可以选择同时或分别使用 i 和 m 标记（1.15 版本）。
• 示例：
  • example.com##body > div:last-of-type span:has-text(/^Promoted by/)：以 “Promoted by” 打头
  • example.com##body > div:last-of-type span:has-text(/^Promoted by/i)：以 “Promoted by” 打头，忽略大小写
  • example.com##body > div:last-of-type span:has-text(Promoted by): 在任意位置出现 “Promoted by”

subject:if(arg)

已在 uBO 1.15.0 中放弃使用，:has(...) 可替代

subject:if-not(arg)

已放弃使用，:not(:has(arg)) 可替代。

subject:matches-css(arg)

• 选择 subject 元素，当且仅当满足对 arg 进行估值的结果是一个或多个元素这个条件。
• 是否可链接：是。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• arg：以 name: value 形式的声明，其中 name 是一个有效的 CSS style 属性，value 是该 style 属性期望的值。value 可以是一个文本或正则表达式。
  • 文本：值必须 严格 匹配浏览器的 getComputedStyle 方法所返回的属性值。
  • 正则表达式：你可以选择同时或分别使用 i 和 m 标记（1.15 版本）。
• 示例：
  • extratorrent.*##body > div[class]:matches-css(position: absolute)
  • facet.wp.pl##div[class^="_"]:matches-css(background-image: /^url\("data:image/png;base64,/)

subject:matches-css-before(arg)

和 :matches-css(...) 一样，除了是对 subject 元素的 :before 伪类查找对应的 style 属性。

subject:matches-css-after(arg)

和 :matches-css(...) 一样，除了是对 subject 元素的 :after 伪类查找对应的 style 属性。

subject:not(arg)

• 描述：选择 subject 元素，当且仅当对 arg 进行估值的结果为零元素。
• 是否可链接：是。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• arg：一条在 subject 元素的上下文中估值了的过程式修饰规则。

该操作符从 uBO 1.17.5b9 开始引入，目的是提高对 AdGuard 过滤规则语法的兼容性。

它的作用是取消其他的过程式操作符。例如 :not(:has(.foo)) 生效场景是没有任何子孙选择符匹配 .foo。

请注意如果 arg 是有效的 CSS 选择符，则 uBO 不会将 :not 这个操作符视作过程式操作符，而是视作 CSS 选择符的一部分。这样就可以完整兼容现有的 CSS :not(...) 伪类。

subject:watch-attrs(arg)

该操作符仍处于实验阶段。

• 描述：可建立一条透传型（Pass-through）规则，用于修改过程式修饰规则引擎的行为，方式为所匹配的元素有一个或多个属性发生变化时强制引擎重新估值。
• 是否可链接：是。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• arg：用逗号分隔的一系列属性名。如不填写参数则表示监测任意一个属性的变化。

该操作符自 uBO 1.17.5rc3 开始引入。

它是用于解决 uBlockOrigin/uBlock-issues#341 (comment) 中提到的问题(overlay dialog used for two purposes, differ only by class name in child node).

By default hiding by procedural filters is reevaluated only when nodes in sub-tree are added or removed - uBO does not watch for attribute changes for performance reasons. This filter instructs uBO procedural filtering engine to watch for changes in specific attributes.

示例：

• vivrehome.pl##.js-popup-register:has(.js-title-default.is-hidden:watch-attributes(class)) 可屏蔽首次访问网站时出现的“注册”叠加框，但在点击 "rejestracja" 后允许显示该叠加框。
• ameshkov.github.io###testdiv:watch-attrs(id):has(p) 可用于检测 id 所发生的变化。

subject:xpath(arg)

• 描述：通过对使用 subject 作为上下文节点（可选的）和 arg 作为表达式的 XPath 进行估值来创建新的元素集合。
• 是否可链接：是。
• subject：可选。可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• arg：一条有效的 XPath 表达式。
• 示例：
  • facebook.com##:xpath(//div[@id="stream_pagelet"]//div[starts-with(@id,"hyperfeed_story_id_")][.//h6//span/text()="People You May Know"])

:xpath(...) 操作符和其他操作符有所不同。其他操作符是用来查找到结果元素集合，而 :xpath(...) 操作符既可以创建结果元素集合也可以查找到已有的结果元素集合。因此，这里的 subject 是可选的。例如，:xpath(...) 操作符可以用来创建由 subject 元素所有祖先元素组成的新的结果元素集合，而这是普通 CSS 选择符或其他过程式操作符所无法做到的。