gkd Documentation

::: details 手机浏览器下载失败?
某些手机浏览器存在自定义拦截会导致下载失败, 建议使用 Via 浏览器下载
:::

其它下载方式

• Google Play   区别
• Github Releases

下载完毕后, 在您的 Android 手机上安装并打开

使用 {#usage} Copy Chapter

打开后进入 GKD 的首页, 要想 GKD 正常工作需要授权无障碍权限

点击无障碍权限右侧的 授权 按钮即可前往设置的无障碍界面授权

以 Xiaomi HyperOS 为例, 下面为完整的授权流程截图

如遇到问题可在 常见问题 查阅解决方案

File: docs/guide/node.md Copy Chapter

属性方法 {#title}

此章节介绍各个类型可用的属性及其方法

null Copy Chapter

[!NOTE] 提示
null 无任何属性方法, 并且在无特殊说明时, 属性方法当调用者或者参数是 null 时, 均返回 null

当 name 是 null 时, name.length 为 null

当 parent 是 null 时, parent.getChild(0) 为 null

当 index 是 null 时, parent.getChild(index) 为 null

boolean Copy Chapter

int Copy Chapter

string Copy Chapter

node Copy Chapter

[!IMPORTANT] 重要提示
此类型下以 _ 开头的属性只能在网页快照调试工具上使用, 真机不可用

context Copy Chapter

context 具有 node 的所有属性方法, 下面只介绍额外属性方法

示例

FrameLayout[prev.name$='ImageView'] > ImageView[current.name=name]

中的 prev 就是 FrameLayout 右侧的 ImageView, current 就是 ImageView

global Copy Chapter

global 具有 context 的所有属性方法, 并且没有任何属性方法能获取 global 的引用, 下面只介绍额外属性方法

示例

[name=''][prev.name=''][current.name=''][parent.name='']

• 第一个 name 来自 global, 实际上任何 xxx/xxx() 都来自 global
• 第二个 prev.name 来自 context
• 后续的 current.name/parent.name 都来自 node

File: docs/guide/optimize.md Copy Chapter

查询优化 {#title}

一些关于查询优化的说明

查找根节点 {#query-root} Copy Chapter

选择器通过满足下列格式的属性选择器标识根节点

• [parent=null]
• A[id='xxx'][parent=null][text='xxx']

即只需存在一个 [parent=null] 就满足条件, 以下是对此的优化

主动查询 {#enforce} Copy Section

一般的选择器如 LinearLayout > TextView, 选择器需要从 根节点/事件节点 使用深度先序顺序遍历子孙节点并判断是否满足条件

如果屏幕上有 n 个节点, 判断逻辑需要运行 n 次

但是如果选择器是类似 TextView <3 LinearLayout <2 [parent=null], 由于在右侧标明了从根节点查找

因此上面的 深度先序顺序遍历子孙节点 将省略, 只进行一次判断, 不需要判断 n 次

但是如果你在子查询里使用 <<n, 例如 TextView <<n [parent=null]

根据上面说明的优化, 虽然也只有一次判断, 但是由于 <<n 导致内部的子判断也是 n 次, 实际上没有优化判断次数

[!TIP] 提示
实际上从根节点开始匹配并且目标不是根节点的选择器如 A > B 都可等价为 A > @B <<n [parent=null]

祖先节点 {#ancestor} Copy Section

在示例 A <3 [parent=null] >n TextView 中, 选择器找到 TextView 后, 根据 >n 表示任意祖先节点

在默认情况下, 如果 TextView 的层级很深, 那必然需要多次调用 获取父节点 才能最终匹配

但是如果左侧的选择器是 [parent=null] >n, 这表示找到根节点, 选择器此时不会去执行多次调用 获取父节点

在 GKD 内部, 根节点可以直接通过 API 获取, 因此 [parent=null] >n 只需要调用一次方法

快速查询 {#fast-query} Copy Chapter

[!NOTE] 注意
此优化需要设置 fastQuery 来启用
并且节点在快照面板被标识 可快速查找, 否则查找不到

查询场景 {#query-scene} Copy Section

一般情况下, 选择器 [vid="name"] 需要从 根节点/事件节点 使用深度先序顺序遍历子孙节点并判断是否满足条件

但是 Android 提供了如下两个快速获取节点的 Api

• findAccessibilityNodeInfosByViewId
• findAccessibilityNodeInfosByText

这使得可以通过 id/vid/text 直接获取子孙节点

对此我们需要规定符合特定条件的选择器来调用这些 Api 从而跳过手动遍历子孙节点

规定格式 {#rule-format} Copy Section

所有 末尾属性选择器的第一个属性选择表达式符合下面的结构之一

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

或者使用 || 将它们连接形成的逻辑表达式也符合条件, 即如下格式

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

这些规定的格式都是为了提取 id/vid/text 来调用上面的两个 Android Api

下面给出实际示例: ✅ 表示符合格式, ❎ 表示不符合格式

• A > B + C[id='x'][childCount=2] ✅
• A > B + C[childCount=2][id='x'] ❎
• A > B + C[id='x' || text='manbaout' || text*='ikun'][childCount=2] ✅
• A > B + C[childCount=2][id='x' || text='manbaout' || text*='ikun'] ❎

这样一个选择器只能在右侧使用快速查询, 为了在中间的子选择器也能使用

额外规定如果属性选择器如果符合上面格式并且右侧是 <<n, 也能在局部使用快速查找

示例 A > B + C[id='x'][childCount=2] <<n D 中的 C[id='x'][childCount=2] <<n 可以使用局部快速查找

下面给出满足局部查询优化的示例: ✅ 表示符合格式, ❎ 表示不符合格式

• A > B + C[id='x'][childCount=2] <<n D ✅
• A > B + C[childCount=2][id='x'] <<n D ❎

上面介绍的是只有一个局部选择器的情况, 下面给出多个局部快速查找的的示例

如 A > C[id='x'] <<n D[id='y'] <<n E, 其中的 C[id='x'] <<n 和 D[id='y'] <<n 都可以使用局部快速查找

如果使用 ||, && 连接多个选择器时, 快速查询为它们的并集

如果选择器被 !(xxx) 包裹, 则不符合快速查询格式, 也就是 ! 会取消其内部所有的快速查询

• (A + B[id='b']) || (C + D[id='d']) 的快速查询为 id='b', id='d'
• (A + B[id='b']) && (C + D[id='d']) 的快速查询为 id='b', id='d'
• (A + B[id='b']) && !(C + D[id='d']) 的快速查询为 id='b'

需要注意的是它们内部的 局部快速查找 仍然独立成立

• (X[id='x'] <<n A + B[id='b']) && !(Y[id='y'] <<n C + D[id='d']) 的快速查询为 id='b', 局部快速查询分别是 id='x', id='y'

[!NOTE] 注意
如果选择器不存在满足快速查找的格式, fastQuery 是否开启都不影响查询复杂度

优化示例 {#optimize-example} Copy Section

以 [vid="image"] <<n [vid="recyclerView"] <<n [vid="content_layout"] 为例

上面的选择器存在 3 个快速查找优化

• [vid="content_layout"] 从 根节点 优化查询找到 content_layout
• [vid="recyclerView"] 从 content_layout 优化查询找到 recyclerView
• [vid="image"] 从 recyclerView 优化查询找到 image

也就是只需要调用 findAccessibilityNodeInfosByViewId 3 次即可得到目标节点

如果是从根节点开始查询, 根据快照内的 选择器路径视图

• [vid="content_layout"] 从 根节点 需要 7 次找到 content_layout
• [vid="recyclerView"] 从 content_layout 需要 48 次找到 recyclerView
• [vid="image"] 从 recyclerView 需要 44 次找到 image

File: docs/guide/privacy.md Copy Chapter

隐私政策 {#title}

版本号：1.0
生效日期：以应用版本发布日期为准

本隐私政策旨在说明我们如何处理您的数据。

GKD 应用秉持 “本地优先、最小权限、完全离线” 原则。

我们不会收集、存储或上传任何用户隐私数据。

一、我们如何处理您的数据 {#p1} Copy Chapter

二、权限使用说明 {#p2} Copy Chapter

三、数据导入与导出说明 {#p3} Copy Chapter

• 所有规则、配置、日志等数据仅保存在用户本地；
• 用户可通过系统分享功能导出文件，无需申请权限；
• 部分旧设备或旧系统中，普通版导出文件可能会申请写入下载目录权限，且用途仅限导出功能。

四、第三方库说明 {#p4} Copy Chapter

本应用所使用的第三方库均为开源项目，不包含任何用户跟踪、统计或联网行为。完整依赖列表可在项目开源仓库中查看。

五、用户权利 {#p5} Copy Chapter

您有权：

• 拒绝授予任何权限
• 随时导出、编辑或删除本地数据
• 卸载应用以终止使用

六、隐私政策变更 {#p6} Copy Chapter

如隐私政策有更新，将随应用更新发布。您可在官网或应用内查阅最新版，继续使用即视为接受变更。

File: docs/guide/selector.md Copy Chapter

选择器 {#title}

一个类似 CSS 选择器的选择器, 能联系节点上下文信息, 更容易也更精确找到目标节点

为什么需要选择器 {#why} Copy Chapter

我们的目的是查询获取屏幕上的某个节点, 最简单的情况下, 目标节点已经有唯一的 id/text 标识

这时只需要配置 id/text 就能简单执行点击, 但实际情况很多节点都缺失了这些信息, 无法简单查询获取

节点还存在很多额外信息没有被利用到, 节点所有属性可以在 快照-14045424 的属性面板看到

另一种常见的情况是节点没有有效属性, 这时我们需要根据周围的节点去定位

选择器就是为了解决这些问题而开发的, 下面是对选择器语法的详细介绍

[!TIP] 提示
本文是从 抽象语法树(AST) 的角度去完备地介绍选择器结构
如果你是初学者, 建议你直接看 选择器-示例

语法 {#syntax} Copy Chapter

与 CSS 类似, 一个选择器由 属性选择器 和 关系选择器 交叉组成, 并且开头末尾必须是 属性选择器

示例 div > img 的结构是 属性选择器 关系选择器 属性选择器, 它表示选择父节点是 div 的 img 节点, 这与 相同 CSS 语法 语义一致

另外 属性选择器 和 关系选择器 之间必须强制用 空白字符(空格/换行/回车/制表) 隔开

即 div>img 非法, 必须写成 div > img

下面分别介绍 属性选择器 和 关系选择器

属性选择 {#attr} Copy Chapter

它和 CSS 语法的 属性选择器很相似, 但更强大, 如下是一个示例

@TextView[a=1][b^='2'][c*='a'||d.length>7&&e=false][!(f=true)][g.plus(1)>0]

@ 表示选择此节点, 一条规则最后属性选择器 @ 生效, 如果没有 @, 取最后一个属性选择器

TextView 代表节点的 name 属性, 而且与 CSS 相似, * 表示匹配任意属性

由于该选择器主要用于 Android 平台, 节点的 name 都是 java 类如 android.text.TextView 这种形式

为了方便书写规则, 上述 TextView 等价 [name='TextView'||name$='.TextView']

[] 内部是一个 逻辑表达式/布尔表达式/取反表达式

• 逻辑表达式 -> name='TextView'||name$='.TextView'
• 布尔表达式 -> name='TextView'
• 取反表达式 -> !(name$='TextView'), !(name='TextView'||name$='.TextView')

注意 取反表达式中的 ! 后面必须是 (...), !!(...) 是非法的

逻辑表达式 有两个操作符 || 和 &&. && 优先级更高

即 [a>1||b>1&&c>1||d>1] 等价于 [a>1||(b>1&&c>1)||d>1]

并列的 [] 视为使用 && 的逻辑表达式, 即 [a=1][b=1] 等价于 [a=1&&b=1]

布尔表达式 由 左值 操作符 右值 构成, 左值/右值 是一个 值表达式

下面分别介绍 值表达式 和 操作符

值表达式 {#value-exp} Copy Chapter

值表达式分两类: 变量 和 字面量, 下图是关系表格

每个值表达式都有其类型, 可细分为两类

基础类型: null boolean int string

对象类型: object

对象类型可细分为 context 和 node 两种类型

比如选择器 [parent=null] 代表选择一个父节点是 null 的节点, 即根节点

上面的 parent 属于 值表达式/变量/标识符, 类型是 node

context 类型指代当前节点的上下文, 当想使用不属于 node 上的属性方法时就需要 context

你可以在 选择器-属性方法 查看所有类型和对应属性方法

变量 {#var} Copy Section

首先需要了解 标识符: 正则匹配 ^[_a-zA-Z][a-zA-Z0-9_]*$ 并且不是 null/true/false 的字符串

示例合法变量名: a ikun manbaout, 下面可输入字符测试否是合法

::: raw

:::

接下来了解 成员表达式 a.b, 它被 . 分为两个部分, 前部分是另一个变量, 后部分是一个标识符作为属性

同理 a.b.c 也是一个 成员表达式, 其中 a.b 是它的变量部分, c 是一个合法的标识符作为属性

根据上面标识符的规则, a.1, a.null, a.true 都是非法成员表达式

最后了解 调用表达式 a(b,c), 它由两个部分构成, ( 的左侧 a 是一个变量作为 调用者

(b,c) 作为调用参数(值类型), 调用参数数量可以是 0 或任意个, 即 a() 也是合法的

合法的其它例子: a.b(c,d).e(f).g(1,2,true)

需要注意调用者不能是 调用表达式, 即 a()() 非法

字面量 {#literal} Copy Section

根据上面的表格, 字面量有 4 种: null, boolean, int, string

• null
• boolean 使用 true/false
• int 匹配 ^-?[0-9]$, 即十进制整数, 示例 -1,0,1, 不支持 +1 这种写法
• string 使用 ' ` " 之一成对包裹, 内部字符转义使用 \
  所有的转义字符示例 \\, \', \", \`, \n, \r, \t, \b, \xfF, \uffFF
  不支持多行字符, 处于 [0, 0x1F] 的控制字符必须使用转义字符表示

此外使用 string 时需要了解 嵌套转义字符 以避免出现错误

操作符 {#attr-operator} Copy Chapter

操作符 用于连接两个 值表达式

附加说明: matches/notMatches 要求 值 必须是合法的 Java/Kotlin 正则表达式, 否则提示语法错误

并且 matches/notMatches 右侧的值只能是 字面量/字符串

操作符只能使用在对应的类型的值, 比如 a>'' 类型不匹配, 将提示 非法类型

下面表格中 - 表示类型不匹配

除 =/!= 以外的操作符, 当节点属性是 null 时表达式为 false

• a > 233
• a >= 233
• a < 233
• a <= 233
• a ^= 'xxx'
• a !^= 'xxx'
• a *= 'xxx'
• a !* 'xxx'
• a $= 'xxx'
• a !$= 'xxx'
• a ~= 'xxx'
• a !~= 'xxx'

即当 a 是 null 时以上表达式为 false

你可能会对 a !$= 'xxx' 在 a 是 null 表达式为 false 感到奇怪

那你可以换一种写法使用 a=null || a!$='xxx' 或 !(a$='xxx')

关系选择 {#connect} Copy Chapter

关系选择器 由 关系操作符 和 关系表达式 构成, 用于连接两个属性选择器

简单示例: div > a, 它 表示/约束 两个节点之间的关系, 下面介绍 关系操作符 和 关系表达式

关系表达式 {#connect-exp} Copy Section

关系表达式 表示查找节点的范围, 有两种

• 元组表达式 (a1,a2,a3,a_n), 其中 a1, a2, a3, a_n 是常量有序递增正整数, 示例 (1), (2,3,5)
• 多项式表达式 (an+b), 其中 a 和 b 是常量整数, 它是元组表达式的另一种表示, 这个元组的数满足集合 {an+b|an+b>=1,n>=1} 如果集合为空集则表达式非法
  当 a<=0 时, 它具有等价的元组表达式
  示例 (-n+4) 等价于 (1,2,3)
  示例 (-3n+10) 等价于 (1,4,7)
  当 a>0 时, 它表示无限的元组表达式
  示例 (n), 它表示 (1,2,3,...) 一个无限的元组
  示例 (2n-1), 它表示 (1,3,5,...) 一个无限的元组

关系操作符 {#connect-operator} Copy Section

关系操作符 表示查找节点的方向, 有 6 种关系操作符

• 前 5 种为 +, -, >, <, <<, 表示节点的相对位置

• 另外一种为 ->, 用于查询过程中, 表示当前节点的之前节点

比如 C ->1 B > A, 由 A 找到 B 后, 此时的 C 就是 B 的之前节点即 A, 这适合想快速去之前节点重新查询关系的场景

将 关系操作符 和 关系表达式 连接起来就得到了 关系选择器

A +(a1,a2,a3,a_n) B : A 是 B 的前置兄弟节点, 并且 A.index 满足 B.index-(a_m), 其中 a_m 是元组的任意一个数字

A -(a1,a2,a3,a_n) B : A 是 B 的后置兄弟节点, 并且 A.index 满足 B.index+(a_m)

A >(a1,a2,a3,a_n) B : A 是 B 的祖先节点, 并且 A.depth 满足 B.depth-(a_m), 根节点的 depth=0

A <(a1,a2,a3,a_n) B : A 是 B 的直接子节点, 并且 A.index 满足 a_m-1

A <<(a1,a2,a3,a_n) B : A 是 B 的子孙节点, 并且 A.order 满足 a_m-1, A.order 是深度优先先序遍历的索引

N ->(a1,a2,a3,a_n) B > A, N 是 B 的之前(右侧)的已查询节点, 并且 N.index 满足 B.index-(a_m), index 顺序为 (n,n-1,...,2,1,0)

表达式简写 {#connect-shortcut} Copy Section

一般情况下, 并不需要写严格完整的表达式, 使用简化写法更方便快捷

下面是一些特殊情况下的简写表示

当 a=0 或 b=0 时, 括号可以省略, 以 + 为例

• A +(3n+0) B -> A +(3n) B -> A +3n B
• A +(0n+3) B -> A +(+3) B -> A +3 B

当 a=0 且 b=1 时, an+b 可以省略, 以 + 为例

• A +(0n+1) B -> A + B

此外 A + B,A > B 都与等价的 CSS 语法语义相同

当 a=1 且 b=0 且操作符是 >, 可以进一步简写, 比如

• A >(1n+0) B -> A >n B -> A B

这与等价的 CSS 语法语义相同

进阶 {#advanced} Copy Chapter

正如上述的 属性选择 一样, 选择器也可以组合为 逻辑表达式/取反表达式

只有一个格式要求: 单个选择器必须强制使用 () 包裹

• 一般选择器 -> A + B 或 (A + B)

• 逻辑或表达式 -> (A + B) || (M > N), 表示匹配节点满足 A + B 或 M > N

  匹配结果遵循 || 的短路原则, 优先判断左侧的 A + B, 如果满足 A + B 那就是 B. 不满足 A + B 时, 判断右侧表达式, 如果满足 M > N 那就是 N, 当然也可以在内部使用 @ 自定义目标节点

• 逻辑且表达式 -> (A + B) && (M > N), 表示匹配节点满足 A + B 和 M > N, 结果取右侧表达式结果, 结果为 N, 当然也可以在内部使用 @ 自定义目标节点

• 取反表达式 -> !(A + B), 表示匹配节点应不满足 A + B, 需要注意的是 !(@A + B) 中的 @ 是无效的, 它的匹配结果只能是末尾节点 B

此外 逻辑且表达式 的优先级更高, 即 (A + B) || (C + B) && (M > N) 等价于 (A + B) || ((C + B) && (M > N))

示例 {#example} Copy Chapter

@LinearLayout > TextView[id=`com.byted.pangle:id/tt_item_tv`][text=`不感兴趣`]

选择器从末尾开始查找, 首先找到 id=`com.byted.pangle:id/tt_item_tv` 和 text=`不感兴趣` 的 TextView, 并且父节点是 LinearLayout 的节点

此时我们得到两个节点 [LinearLayout, TextView] 根据 @ 知道目标节点是 LinearLayout

实际上它与

TextView[id=`com.byted.pangle:id/tt_item_tv`][text=`不感兴趣`] <n LinearLayout

的目标匹配节点是等价的, 但是在查询算法时间复杂度上, 后者更慢

如下是网页无障碍快照审查工具, 使用它的搜索框的选择器查询可以实时测试编写的选择器

• 快照-14045424
• 快照-14034770
• 快照-14031920
• 快照-14018243
• 快照-14011298
• 快照-13999908

一些注意 {#note} Copy Chapter

匹配顺序 {#match-order} Copy Section

选择器的匹配顺序是 从右往左匹配

例如 FrameLayout > TextView, 它是先从 根节点/事件节点 找到 TextView, 然后再判断 parent 是不是 FrameLayout

并不是先找到 FrameLayout 然后再判断 child 是否有 TextView

同时在 选择器路径视图 也会标明匹配顺序和查找方向

正则表达式优化 {#regex-optimization} Copy Section

对 matches/notMatches 的优化: 如果正则表达式满足下面的条件, 选择器将使用内置的简单的函数匹配, 而不是真正地去运行一个正则表达式

• [text~="(?is)abc.*"] -> startsWith('abc', ignoreCase = true)
• [text~="(?is).*abc.*"] -> contains('abc', ignoreCase = true)
• [text~="(?is).*abc"] -> endsWith('abc', ignoreCase = true)
• [text!~="(?is)abc.*"] -> notStartsWith('abc', ignoreCase = true)
• [text!~="(?is).*abc.*"] -> notContains('abc', ignoreCase = true)
• [text!~="(?is).*abc"] -> notEndsWith('abc', ignoreCase = true)

上面的 abc 指代不包含 \^$.?*|+()[]{} 这类特殊正则字符的任意字符串, 如 ikun 符合, ikun? 不符合, ignoreCase = true 表示忽略大小写

简单来说就是如果你只想忽略大小写去简单匹配或不匹配一些字符串, 那么直接使用上面的格式

正则表达式一致性 {#regex-multiplatform} Copy Section

由于 选择器 需要同时满足 浏览器/Js(审查工具), Android/Java(GKD) 运行, 而这两个平台的正则表达式的底层实现和语法表示略有不同

因此为了在 Js 端实现和 Java 一致的正则表达式规范, 网页审查工具借助 Kotlin Wasm 将正则表达式的 matches 函数接口编译为 wasm 提供给 Js 调用

Kotlin Wasm 需要你的浏览器支持 WasmGC, 也就是版本需要满足下列条件

TextView[text="\\\n"]

{
  matches: 'TextView[text="\\\n"]',
}

TextView[text="\
"]

{
  matches: 'TextView[text="\\\\\\n"]',
}

TextView[text~="\d"]

TextView[text~="\\d"]

Regex("\\d").matches(text)

{
  matches: 'TextView[text~="\\\\d"]',
}

{
  matches: 'TextView[text~="\\\\\\\\"]',
}

{
  matches: 'TextView[text="\\\\"]',
}