本页为译文。如有出入,以英文页面为准。

高级参考 · 高级

页面修复和 scriptlet

了解内置的页面修复和 scriptlet 语法。Shield AdBlock 1.0.2 不会从添加的列表或自定义规则中执行该语法。

概述

页面修复 使用 Shield 内置的小型辅助程序,修改范围明确的页面行为。过滤器可以选择受支持的辅助程序及其参数;但不能提供新的 JavaScript 代码让 Shield 下载并运行。

页面修复 开关控制内置修复。这些内置修复仍是单独的设置,并继续使用 Shield 自带的辅助程序。在 Chrome、Edge 和 Firefox 上,Shield AdBlock 1.0.2 软件包都不包含 添加来源中的修复,也不包含你自己编写的规则中的 scriptlet。高级设置 可以显示高级控件;显示这些控件并不会加入被省略的这一层级。

这些 1.0.2 软件包包含内置修复,但省略了添加的列表和自定义规则中的 scriptlet 层级。即使内置修复在主页面上生效,从其他网站嵌入的内容也可能不受影响。

语法

本指南中的示例展示的是过滤器语法。在 Shield AdBlock 1.0.2 软件包中,它们不是可从添加的列表或自定义规则中执行的 scriptlet。该设置开启时,内置的页面修复会继续使用软件包中的辅助程序。

请使用限定主机的形式,例如:

news.example##+js(set-constant, adBlockDetected, false)

这会为该网站请求软件包中的 set-constant 辅助程序。它不是 JavaScript 源代码或 CSS,也不能保证网站使用了该属性。参数以逗号分隔;转义的逗号按字面处理,并会去掉一层匹配的外层引号。

当前辅助程序清单

此版本可识别以下十个规范名称。参数数量范围不包括辅助程序名称。示例展示的是 +js(...) 内的调用;请在每个调用前加上你有意选择的网站范围,例如 news.example##。

横向滚动以查看完整表格。

辅助程序和别名 用途和参数 示例 预期效果和限制
set-constant; set 将以点分隔的属性设为一个允许的值;正好 2 个参数。 +js(set-constant, adBlockDetected, false) 设置受支持的常量行为。任意字符串、代码和无上限的数字会被拒绝。
abort-current-script; acs, abort-current-inline-script, acis 在当前脚本访问某个属性时将其停止;属性加上可选的内容和来源匹配文本,1–3 个参数。 +js(abort-current-script, adblock) 作用于匹配的脚本访问,而不是页面上的所有脚本。匹配文本必须是字面值。
abort-on-property-read; aopr 在代码读取某个属性时将其停止;正好 1 个参数。 +js(abort-on-property-read, adblock) 影响指定的属性链,该属性链必须是简单的点分隔标识符路径。
abort-on-property-write; aopw 在代码写入某个属性时将其停止;正好 1 个参数。 +js(abort-on-property-write, antiAdblock.write) 针对该属性链;可能导致向其写入的正常代码出错。
prevent-addEventListener; aeld, addEventListener-defuser 阻止注册匹配的监听器;事件和处理程序源码的字面值,正好 2 个参数。 +js(prevent-addEventListener, click, antiAdblock) 两个条件都必须匹配。空条件或 ! 不能让整个请求变成无条件生效;正则表达式和其他拦截器的额外选项会被拒绝。
prevent-fetch; no-fetch-if 阻止页面中匹配的 fetch;条件加上可选的响应标记,1–2 个参数。 +js(prevent-fetch, url:ads method:POST, emptyObj) 匹配所提供的全部字面条件,并返回所选的空响应。它不会取消浏览器层面的所有请求类型。
prevent-xhr; no-xhr-if 阻止匹配的 XMLHttpRequest;条件加上可选的响应标记,1–2 个参数。 +js(prevent-xhr, url:collect method:POST, emptyArr) 使用 URL 和方法条件;仅适用于 fetch 的 mode: 条件会被拒绝。
json-prune 删除 JSON 属性;要删除的路径加上可选的必需路径,1–2 个参数。 +js(json-prune, payload.secret, payload.ready) 当必需路径存在时,修剪匹配的 JSON 结构。这是一种有限制的路径语言,而不是任意的 JSONPath。
prevent-window-open; nowoif, no-window-open-if, window.open-defuser 阻止匹配的 window.open 调用;0–1 个字面参数。 +js(prevent-window-open) 没有条件时,会阻止其适用范围内的调用。字面匹配可能检查合并后的全部调用参数,而不仅是 URL;替换和延迟选项会被拒绝。
prevent-setTimeout; nostif, no-setTimeout-if, setTimeout-defuser 阻止匹配的定时器;可选的回调匹配文本和可选的延迟,0–2 个参数。 +js(prevent-setTimeout, adRefresh, 1000) 匹配回调文本和所提供的延迟。延迟必须是有限值;正则表达式参数和额外选项会被拒绝。

规范名称和别名也可以带 .js 后缀。在新规则中,建议使用规范名称,让意图更容易理解。

参数边界

属性类辅助程序接受点分隔的标识符,不接受方括号表达式、函数调用或会触及原型的属性链。set-constant 接受以下命名值:undefined、false、true、null、noopFunc、trueFunc、falseFunc、noopPromiseResolve、noopPromiseReject、emptyObj 和 emptyArr,以及受支持的空值形式和 −32767 到 32767 之间的整数。

请求类辅助程序接受以空白分隔、有限制的字面条件。字段名称为 url、method,以及仅适用于 fetch 的 mode。没有字段名的条件表示 URL 子字符串。可以用 ! 表示否定;所有条件都必须匹配。响应标记包括默认的空文本、emptyStr、emptyObj 和 emptyArr。未知字段或响应标记会被拒绝。

JSON 修剪使用以空白分隔的点分隔路径。其有限制的路径段可以包含受支持的 *、[]、[-] 和 {-} 形式,但在位置和处理量上有限制。会触及原型的路径会被拒绝。除非你已核实确切的嵌套结构和想要的效果,否则建议使用简单的命名路径。

限制

仅仅识别出 scriptlet 名称,并不足以让规则运行。规则的参数数量、参数语法、网站范围和开关都必须符合要求,而且软件包必须包含该层级。Shield AdBlock 1.0.2 软件包省略了添加的列表和自定义规则中的 scriptlet,因此,符合此语法的规则不会从你添加的列表或你编写的规则中执行。正则表达式参数、未知名称和不受支持的额外选项会导致整条规则被跳过。AdGuard 的 #%# scriptlet 语法不能用来代替 ##+js(...)。

内置修复有各自的适用条件和注册状态。配置或注册成功,并不能证明辅助程序已经运行、拦截了预期的调用或移除了可见的广告。没有任何辅助程序能保证移除 YouTube 广告,或与其他拦截器所有版本的 scriptlet 兼容。

示例

要在某个网站上停用指定的辅助程序,请使用 scriptlet 例外:

news.example#@#+js(set-constant)

仅包含名称的例外会在匹配的范围内停用该辅助程序。news.example#@#+js() 是范围更大的全部 scriptlet 例外。这些例外不会停用网络规则或外观规则。请像检查调用一样仔细检查例外,并在更改后重新加载网站。

仍需帮助?联系支持