RawAppRule

应用规则

Extends

• RawRuleProps.RawAppRuleProps

Properties

actionCd?

optional actionCd: Integer

单位: 毫秒

当前规则的冷却时间, 或者执行 action 最小间隔

Default

1000

Inherited from

RawRuleProps.actionCd

---

actionDelay?

optional actionDelay: Integer

单位: 毫秒

延迟执行: 查询到节点->等待一段时间->再次查询到节点则执行对应 action

Inherited from

RawRuleProps.actionDelay

---

quickFind?

optional quickFind: boolean

注意: 将在未来版本弃用此属性, 请使用 fastQuery 代替

如果开启, 此规则下的所有 末尾属性选择器的第一个属性选择表达式符合下面的结构之一的选择器 将使用快速查找

• [id='abc']
• [vid='abc']
• [text='abc']
• [text^='abc']
• [text*='abc']
• [text$='abc']

比如 A > B + C[id='x'][childCount=2] 符合, 但 A > B + C[childCount=2][id='x'] 不符合

它的底层原理是 跳过手动遍历所有节点 直接调用 findAccessibilityNodeInfosByViewId / findAccessibilityNodeInfosByText 得到可匹配节点

大多数情况下都能查询到, 在少数某些复杂结构下, 即使目标节点存在, 快速查询也不一定查询到

比如 Image < @View + View >2 [text*='广告'] 虽然符合快速查询的条件但是使用 findAccessibilityNodeInfosByText("广告") 并不能查询到节点

它是优点是快速, 因为遍历所有节点是一个耗时行为, 虽然多数情况下这种耗时较低

但是在某些软件比如 哔哩哔哩 的开屏广告在这种耗时下延迟可达 1-2s, 这也是导致 gkd-kit/gkd#60 的原因

如果你想对某个局部选择器关闭快速查找,只需要调整你的选择器的属性选择表达式的顺序使得它不符合快速查找的条件即可

Default

false

Inherited from

RawRuleProps.quickFind

---

fastQuery?

optional fastQuery: boolean

如果开启, 此规则下的所有满足 特定格式的选择器 将使用快速查找优化查询速度

详细文档请查看 查询优化

Default

false

Inherited from

RawRuleProps.fastQuery

---

matchRoot?

optional matchRoot: boolean

此规则下的所有选择器是否直接从根节点开始匹配

GKD 的原理是监听系统屏幕节点变化 这时候会接收到一个事件节点, 默认从这个节点开始匹配到其子孙节点

常见情况是: 如果匹配的速度跟不上节点事件数量的产生速度, 下一次匹配的开始节点将变成根节点

但是如果节点事件产生速度较慢, 比如屏幕上只有一个节点(文本)在变化, 那么开始匹配的节点一直将是这个节点

此时如果你的选择器的末端属性选择器选择的不是这个节点, 那么匹配将会失败, 即使你能在网页审查工具查询到这个节点

为了解决这个问题, 你可以设置 matchRoot=true, 这样每次匹配都会从根节点开始匹配

以 快照-16105497 为例, 事件节点总是 _id=8 的节点, 此时如果你的选择器是 [text*="15秒"] - [text*="跳过"]

在 matchRoot=false 的情况下, 你的匹配范围如下蓝框

而在 matchRoot=true 的情况下, 你的匹配范围如下蓝框

Default

false

Inherited from

RawRuleProps.matchRoot

---

matchDelay?

optional matchDelay: Integer

单位: 毫秒

匹配延迟

规则准备匹配/或被唤醒时, 等待一段时间, 使此规则参与查询屏幕节点

Inherited from

RawRuleProps.matchDelay

---

matchTime?

optional matchTime: Integer

单位: 毫秒

规则匹配时间, 此规则参与查询屏幕节点时, 等待一段时间, 休眠此规则

例如某些应用的 开屏广告 的 activityId 容易误触/太广泛, 而开屏广告几乎只在应用切出来时出现, 设置一个有限匹配时间能避免后续的误触

Inherited from

RawRuleProps.matchTime

---

actionMaximum?

optional actionMaximum: Integer

最大执行次数

规则的 action 被执行的最大次数, 达到最大次数时, 休眠此规则

功能类似 matchTime, 适用于只需要执行一次的: 开屏广告/更新弹窗/青少年弹窗 一类规则

当规则准备匹配/或被唤醒时, 将重新计算次数

Inherited from

RawRuleProps.actionMaximum

---

resetMatch?

optional resetMatch: "activity" | "app"

当规则因为 matchTime/actionMaximum 而休眠时, 如何唤醒此规则

Default

'activity'

Examples

'activity'
// 当 activity 刷新时, 唤醒规则
// 刷新 activity 并不代表 activityId 变化
// 如 哔哩哔哩视频播放页 底部点击推荐视频 进入另一个 视频播放页, 进入了新 activity 但是 activityId 并没有变化

'app'
// 重新进入 app 时, 唤醒规则

Inherited from

RawRuleProps.resetMatch

---

actionCdKey?

optional actionCdKey: Integer

与这个 key 的 rule 共享 cd

比如开屏广告可能需要多个 rule 去匹配, 当一个 rule 触发时, 其它 rule 的触发是无意义的

如果你对这个 key 的 rule 设置 actionCd=3000, 那么当这个 rule 和 本 rule 触发任意一个时, 在 3000 毫秒 内两个 rule 都将进入 cd

Inherited from

RawRuleProps.actionCdKey

---

actionMaximumKey?

optional actionMaximumKey: Integer

与这个 key 的 rule 共享次数

比如开屏广告可能需要多个 rule 去匹配, 当一个 rule 触发时, 其它 rule 的触发是无意义的

如果你对这个 key 的 rule 设置 actionMaximum=1, 那么当这个 rule 和 本 rule 触发任意一个时, 两个 rule 都将进入休眠

Inherited from

RawRuleProps.actionMaximumKey

---

order?

optional order: Integer

规则参与匹配的顺序, 数字越小越先匹配

如果两个规则 order 相同, 按照 groups 中的数组顺序匹配, app 类型规则顺序优先于 global 类型规则

属于不同订阅的规则按照订阅列表中顺序匹配, 长按订阅卡片可以拖动排序

Default

0

Inherited from

RawRuleProps.order

---

forcedTime?

optional forcedTime: Integer

单位: 毫秒

在开始匹配后的一段时间内, 不管界面没有通知变化, 主动使此规则参与屏幕查询

GKD 借助 onAccessibilityEvent 感知界面变化

但是某些基于 flutter/webview 开发的应用/页面在变化时并不会通知系统去触发 onAccessibilityEvent, 但是屏幕上的节点信息确实产生变化

唯一的办法是在开始匹配的一定时间内主动查询屏幕节点

Inherited from

RawRuleProps.forcedTime

---

priorityTime?

optional priorityTime: Integer

设置一个优先级时间, 在优先级时间内, 此规则为 优先级规则

如果规则参与匹配, 匹配顺序为 优先级规则(内部 order 排序) -> 普通规则(内部 order 排序)

当新无障碍事件到来时, 如果当前匹配规则是普通规则, 则中断匹配操作重新匹配

优先时间过后, 规则将变为普通规则

使用场景: 某些应用开启很多规则, 导致开屏一类规则被其他规则阻塞, 可以设置优先级时间让开屏规则优先匹配

注意: 如果全部规则都是优先级规则或只有一个规则, 则不会发生中断行为

Inherited from

RawRuleProps.priorityTime

---

priorityActionMaximum?

optional priorityActionMaximum: Integer

优先级执行次数, 触发多少次后, 规则将变为普通规则

Default

1

Inherited from

RawRuleProps.priorityActionMaximum

---

snapshotUrls?

optional snapshotUrls: IArray<string>

当前 规则/规则组 的匹配界面快照链接, 增强订阅可维护性

Inherited from

RawRuleProps.snapshotUrls

---

excludeSnapshotUrls?

optional excludeSnapshotUrls: IArray<string>

当前 规则/规则组 的排除匹配界面的快照链接

Inherited from

RawRuleProps.excludeSnapshotUrls

---

exampleUrls?

optional exampleUrls: IArray<string>

当前 规则/规则组 的规则在手机上的运行示例, 支持 jpg/png/webp/gif

如果规则是多个规则组合起来的, 可以更好看懂规则到底在干啥, 比如 点击关闭按钮-选择关闭原因-确认关闭 这种广告用 gif 看着更清楚在干啥

Inherited from

RawRuleProps.exampleUrls

---

key?

optional key: Integer

当前规则在列表中的唯一标识

key 没有顺序大小之分, 可以是任意数字

设置后不可更改, 否则造成点击记录错乱

Inherited from

RawRuleProps.key

---

name?

optional name: string

规则名称

Inherited from

RawRuleProps.name

---

preKeys?

optional preKeys: IArray<Integer>

要求当前列表里某个 key 刚刚执行

比如: 点击关闭按钮-选择关闭原因-确认关闭, key 分别是 1,2,3, preKeys 分别是 [],[1],[2]

那么 选择关闭原因 必须要求 点击关闭按钮 刚刚执行过才能执行, 确认关闭 也要求 选择关闭原因 刚刚执行过才执行

否则后面的规则不会触发, 也就是要求规则按顺序执行, 这是为了防止规则匹配范围太过广泛而误触

Inherited from

RawRuleProps.preKeys

---

action?

optional action: "click" | "clickNode" | "clickCenter" | "back" | "longClick" | "longClickNode" | "longClickCenter"

规则匹配后的操作行为

在 position 存在的情况下, action 的默认值为 clickCenter

Examples

`click`
// 为默认值, 如果目标节点是 clickable 的, 则使用 `clickNode`, 反之使用 `clickCenter`
// 并且当 `clickNode` 事件没有被应用接收时, 则使用 `clickCenter`

`clickNode`
// 向系统发起一个点击无障碍节点事件. 即使节点在屏幕外部/或者被其它节点遮挡,也依然能够正确触发点击目标节点
// 但是如果目标节点不是 clickable 的, 目标应用通常不响应这个点击事件, 也就是点击无效果
// 在极少数情况下, 即使节点是 clickable 的,应用显示接收但是不响应节点点击事件, 此时需要手动设置 `clickCenter`

`clickCenter`
// 计算出此控件的中心的坐标并且如果这个坐标在屏幕内部，那么就向系统发起一个点击屏幕坐标事件
// 如果这个坐标不在屏幕内部, 当作未匹配
// 另外如果目标节点的位置被其它节点遮挡覆盖, 则会点击触发最上层的节点(可能不是目标节点)

`back`
// 向系统发起一个返回事件, 相当于按下返回键

`longClick`
// 如果目标节点是 longClickable 的, 则使用 `longClickNode`, 反之使用 `longClickCenter`
// 并且当 `longClickNode` 事件没有被应用接收时, 则使用 `longClickCenter`

`longClickNode`
// 向系统发起一个长按无障碍节点事件，与 clickNode 类似

`longClickCenter`
// 与 clickCenter 类似, 长按时间为 400 毫秒

Inherited from

RawRuleProps.action

---

position?

optional position: Position

在使用 clickCenter/longClickCenter 时的自定义点击位置

默认坐标为节点中心

如果计算出的坐标不在屏幕内部, 当作未匹配

在 position 存在的情况下, action 的默认值为 clickCenter

Inherited from

RawRuleProps.position

---

matches?

optional matches: IArray<string>

一个或者多个合法的 GKD 选择器, 如果所有选择器都能匹配上节点, 那么点击最后一个选择器的目标节点

点击优先级大于 anyMatches

Inherited from

RawRuleProps.matches

---

anyMatches?

optional anyMatches: IArray<string>

一个或者多个合法的 GKD 选择器, 如果存在一个选择器能匹配上节点, 那么点击这个节点

如果 anyMatches 的所有选择器都无法匹配, 则停止匹配此规则

与 matches 一起使用时, 仍然点击 matches 的最后一项

Inherited from

RawRuleProps.anyMatches

---

excludeMatches?

optional excludeMatches: IArray<string>

一个或者多个合法的 GKD 选择器, 如果存在一个选择器匹配上节点, 则停止匹配此规则

Inherited from

RawRuleProps.excludeMatches

---

activityIds?

optional activityIds: IArray<string>

如果 界面Id startWith activityIds 的任意一项, 则匹配

如果要匹配所有界面: undefined (不填写) 或者 [] (避免使用上级属性)

如果 activityId 以 . 开头, 则等价于 appId + activityId

示例: com.tencent.mm (微信) 的某界面 .MainActivity 等价于 com.tencent.mm.MainActivity

Inherited from

RawAppRuleProps.activityIds

---

excludeActivityIds?

optional excludeActivityIds: IArray<string>

如果 设备界面Id startWith excludeActivityIds 的任意一项, 则排除匹配

优先级高于 activityIds

当 activityId 以 . 开头时, 与 activityIds 识别规则一致

Inherited from

RawAppRuleProps.excludeActivityIds

---

versionNames?

optional versionNames: IArray<string>

如果应用版本名称包含在此列表中, 则匹配

Inherited from

RawAppRuleProps.versionNames

---

excludeVersionNames?

optional excludeVersionNames: IArray<string>

如果应用版本名称包含在此列表中, 则排除匹配, 优先级高于 versionNames

Inherited from

RawAppRuleProps.excludeVersionNames

---

versionCodes?

optional versionCodes: IArray<Integer>

如果应用版本代码包含在此列表中, 则匹配

Inherited from

RawAppRuleProps.versionCodes

---

excludeVersionCodes?

optional excludeVersionCodes: IArray<Integer>

如果应用版本代码包含在此列表中, 则排除匹配, 优先级高于 versionCodes

Inherited from

RawAppRuleProps.excludeVersionCodes