GKD

深色主题

RawAppGroup ​

应用规则组

Extends ​

Properties ​

rules ​

rules: IArray<string | RawAppRule>

应用规则组的规则列表, 支持多种类型, 下面介绍它的两种简单类型的表示意义

示例-1: 简单的字符串直接表示规则的 matches

json5
{
  rules: 'A > B'
}

等价于

json5
{
  rules: {
    matches: 'A > B',
  }
}

示例-2: 也可以是字符串数组表示多个规则的 matches

json5
{
  rules: ['A > B', 'A > B']
}

等价于

json5
{
  rules: [
    {
      matches: 'A > B',
    },
    {
      matches: 'A > B',
    },
  ],
}

actionCd? ​

optional actionCd: Integer

单位: 毫秒

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

Default ​

ts
1000

Inherited from ​

RawGroupProps.actionCd

actionDelay? ​

optional actionDelay: Integer

单位: 毫秒

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

Inherited from ​

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

ts
false

Inherited from ​

RawGroupProps.quickFind

fastQuery? ​

optional fastQuery: boolean

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

详细文档请查看 查询优化

Default ​

ts
false

Inherited from ​

RawGroupProps.fastQuery

matchRoot? ​

optional matchRoot: boolean

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

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

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

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

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

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

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

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

image

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

image

Default ​

ts
false

Inherited from ​

RawGroupProps.matchRoot

matchDelay? ​

optional matchDelay: Integer

单位: 毫秒

匹配延迟

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

Inherited from ​

RawGroupProps.matchDelay

matchTime? ​

optional matchTime: Integer

单位: 毫秒

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

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

Inherited from ​

RawGroupProps.matchTime

actionMaximum? ​

optional actionMaximum: Integer

最大执行次数

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

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

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

Inherited from ​

RawGroupProps.actionMaximum

resetMatch? ​

optional resetMatch: "activity" | "app"

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

Default ​

ts
'activity'

Examples ​

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

Inherited from ​

RawGroupProps.resetMatch

actionCdKey? ​

optional actionCdKey: Integer

与这个 key 的 rule 共享 cd

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

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

Inherited from ​

RawGroupProps.actionCdKey

actionMaximumKey? ​

optional actionMaximumKey: Integer

与这个 key 的 rule 共享次数

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

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

Inherited from ​

RawGroupProps.actionMaximumKey

order? ​

optional order: Integer

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

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

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

Default ​

ts
0

Inherited from ​

RawGroupProps.order

forcedTime? ​

optional forcedTime: Integer

单位: 毫秒

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

GKD 借助 onAccessibilityEvent 感知界面变化

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

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

Inherited from ​

RawGroupProps.forcedTime

priorityTime? ​

optional priorityTime: Integer

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

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

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

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

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

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

Inherited from ​

RawGroupProps.priorityTime

priorityActionMaximum? ​

optional priorityActionMaximum: Integer

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

Default ​

ts
1

Inherited from ​

RawGroupProps.priorityActionMaximum

snapshotUrls? ​

optional snapshotUrls: IArray<string>

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

Inherited from ​

RawGroupProps.snapshotUrls

excludeSnapshotUrls? ​

optional excludeSnapshotUrls: IArray<string>

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

Inherited from ​

RawGroupProps.excludeSnapshotUrls

exampleUrls? ​

optional exampleUrls: IArray<string>

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

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

Inherited from ​

RawGroupProps.exampleUrls

key ​

key: Integer

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

也是客户端禁用/启用此规则组的依据

设置后不可更改, 否则造成客户端启用/禁用错乱

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

Inherited from ​

RawGroupProps.key

name ​

name: string

规则组名称

Inherited from ​

RawGroupProps.name

desc? ​

optional desc: string

规则组描述

Inherited from ​

RawGroupProps.desc

enable? ​

optional enable: boolean

控制规则默认情况下是启用还是禁用

Default ​

ts
true

Inherited from ​

RawGroupProps.enable

scopeKeys? ​

optional scopeKeys: IArray<Integer>

其它 group 的 key, 允许将目标组的所有 rule 添加到当前组的作用域

假设 group1[key=1] 有一个 rule1[key=11], group2[key=2] 有 rule2[key=22], rule3[key=23]

如果 group1 的 scopeKeys=[2] 并且 group2 没有被禁用, 那么 rule1 的 preKeys/actionCdKey/actionMaximumKey 可以是 11/22/23

如果存在相同 key 的 rule, 优先使用本组的 rule, 其次按 scopeKeys 的顺序查找其它组的 rule

Inherited from ​

RawGroupProps.scopeKeys

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

Released under the GPL-v3 License.

Copyright © 2024 GKD. All rights reserved