08.插件命令zm 紫猫插件zm 元素节点
, ,

zm.ElementFind 超级查找元素

文章目录
  1. 1. 功能
  2. 2. 语法
  3. 3. 参数
  4. 4. 返回值
  5. 5. 示例
  6. 6. 备注

功能

根据条件查找元素节点, 返回元素节点表信息与中心坐标等数据. 比 Element.Find() 更加强大, 具体特色如下

  • 除了返回抓抓上显示的元素特征信息外, 还有中心坐标, index等数据
  • 支持指定范围查找, 再也不用担心找到范围外的元素节点了, 甚至直接获取指定范围内的节点
  • 支持指定坐标查找, 直接获取该坐标点的元素节点, 不用再考虑特征串之类的了
  • 支持抓抓上的五大元素特征串, 分别是 text, resource-id, class, package, content-desc, 这5个元素特征串可自由填写任意数量, 且没有顺序要求, 每个特征串之间为 And 关系
  • 除了支持普通的完整匹配外, 还支持正则匹配模式, 让元素特征串更加灵活
  • 默认仅获取最终子节点, 避免干扰, 但你也可以改为获取任意一个符合条件的节点
  • 担心查找的时候节点还没出现? 限时循环查找完美解决这个问题
  • 大量可选参数, 减少不必要的代码量
  • 支持对象参数写法, 将所有参数保存到一张表里, 直接传入该表, 方便优化代码结构

语法

结果 = zm.ElementFind([对象, …][x1,y1,x2,y2,][元素特征, …][指定坐标x,指定坐标y,][是否最终元素,][匹配模式][,超时时间])

参数

参数 数据类型 解释
对象 表 可选, 对象是指把查找一个元素用到的参数全部放到数组中, 然后用该数组做对象参数. 若要填写对象参数, 则必须写在最前面, 填写后将忽略除超时参数以外的其他普通参数. 支持多个对象参数, 每个对象为 OR 关系, 找到任何一个对象立即返回结果
x1 数值型 可选, 查找范围左上角x, 元素节点必须完全在范围内, 不能超出范围, 省略默认为0, 范围0,0,0,0表示全屏
y1 数值型 可选, 查找范围左上角y, 元素节点必须完全在范围内, 不能超出范围, 省略默认为0, 范围0,0,0,0表示全屏
x2 数值型 可选, 查找范围右下角x, 元素节点必须完全在范围内, 不能超出范围, 省略默认为0, 范围0,0,0,0表示全屏
y2 数值型 可选, 查找范围右下角y, 元素节点必须完全在范围内, 不能超出范围, 省略默认为0, 范围0,0,0,0表示全屏
元素特征 字符串 可选, 抓抓上获取到的元素特征值, 支持 text, resource-id, class, package, content-desc这5个对应特征值, 可自由填写0到5个元素特征参数, 无顺序要求, 同个对象每个特征之间为 AND 关系, 内部忽略特征名, 只判断特征值, 详见例子
指定坐标x 数值型 可选, 直接获取指定坐标上的元素特征串, 省略默认为0, 指定坐标0,0表示不使用本参数
指定坐标y 数值型 可选, 直接获取指定坐标上的元素特征串, 省略默认为0, 指定坐标0,0表示不使用本参数
是否最终元素 布尔型 可选, 是否只获取没有子节点的最终元素节点, 省略默认为true, 表示只获取没有子节点的最终元素元素
匹配模式 数值型 可选, 元素特征的匹配模式, -1表示直接比较是否相等的完整匹配模式, -2表示正则匹配是否符合的正则模式, 省略默认为-1
超时时间 数值型 可选, 最大查找时间, 如果每个对象内都有超时时间的话, 将仅使用最大的时间做判断

返回值

表 , 找到返回元素特征表, 没找到返回 null, 元素特征表格式为 {"x":0,"y":0,"id":0,"xy":[0,0]"index":0,"text":"","resource-id":"","class":"","package":"","content-desc":"","checkable":true,"checked":true,"clickable":true,"enabled":true,"focusable":true,"focused":true,"scrollable":true,"long-clickable":true,"password":true,"selected":true,"bounds":[0,0,0,0],"left":0,"top":0,"right":0,"bottom":0,"pos":[0,0]} , 其中 "x", "y" 代表找到元素节点的中心位置坐标, 可用于tap点击, "id" 代表多个对象情况下找到的那个序号

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
Import "zm.luae" //导入插件,只需执行一次
zm.Init  //初始化插件,只需执行一次

//--------------------简易用法--------------------//
//下面这个例子实现了限时5秒钟内获取并点击桌面显示的微信App坐标
//这里找到的坐标为元素中心的坐标
Dim 微信 = zm.ElementFind("微信", 5000)
If 微信 Then 
	TracePrint "找到微信的坐标为: ", 微信["x"], 微信["y"]
	zm.Tap 微信["x"], 微信["y"]
	//小技巧: 返回值中另一个xy成员是数组表, 可以直接被zm.tap调用
	//zm.Tap 微信["xy"] //这句代码也实现了点击坐标功能
Else 
	TracePrint "没找到微信"
End If


//--------------------获取元素文本--------------------//
//获取右上角的时间文本
//这里3个参数是And关系, 也就是要在抓抓上的5个特征中同时找到符合这3个参数值
Dim 时钟 = zm.ElementFind("com.android.systemui:id/clock", "android.widget.TextView","com.android.systemui")
If 时钟 Then 
	TracePrint "当前时间为: ", 时钟["text"]
Else 
	TracePrint "没找到时钟"
End If

//--------------------指定坐标--------------------//
//获取指定坐标的元素文本内容
//一般指定坐标情况下必定有元素的存在, 但该元素不一定有text文本内容
//所以建议是再加上一些元素特征串, 避免获取到的内容不是自己想要的数据
//另外默认仅获取最后一个子元素节点, 如果该坐标只有父节点的话, 请修改布尔值参数
Dim 指定坐标文本 = zm.ElementFind("android.view.View", 650, 1222, 2000)
If 指定坐标文本 Then 
	TracePrint "指定坐标的元素文本为:", 指定坐标文本["text"]
Else 
	TracePrint "没找到元素"
End If

//--------------------指定范围--------------------//
//在固定范围内查找符合条件的元素
//当你发现有大量元素特征重复的情况下, 除了可以用指定坐标解决外, 也可以用指定范围
//指定范围必须要完全包括元素, 例如元素边框是100,100,200,200, 那么范围必须比它大
//如果担心元素不对, 可以加上一些特征串, 这里省略不加
Dim 范围元素 = zm.ElementFind(90, 90, 210, 210)
If 范围元素 Then 
	TracePrint "范围元素的元素坐标与文本为:", 范围元素["x"], 范围元素["y"], 范围元素["text"]
Else 
	TracePrint "没找到元素"
End If

//--------------------对象用法--------------------//
//对象嘛, 肯定是要你自己去找到, 找不到咋办?自己创建一个呗, 咳咳
//所谓的对象其实就是把所有用到普通参数放到一个table数组中
//有了对象后, 将忽略除了超时时间外的所有普通参数, 多个超时时间仅取最大值
//允许填写多个对象, 内部将会循环查找, 找到任何一个对象立即返回结果
//对象参数必须从第1个参数位置开始填写
//下面定义对象的特征串与超时时间, 其他参数也可以写进来
Dim 京东对象 = {"京东","android.widget.TextView","com.android.launcher3", 1000}
Dim 淘宝对象 = {"淘宝","android.widget.TextView","com.android.launcher3", 2000}
//传入多个对象与另一个超时时间, 由于5000大于1000, 所以超时最终为5000毫秒
//假如外面不写超时的话, 那最终超时时间由两个对象决定出最大值为2000毫秒
Dim 对象结果 = zm.ElementFind(京东对象, 淘宝对象, 5000)
If 对象结果 Then 
	TracePrint "找到了一个对象, 坐标为:", 对象结果["x"], 对象结果["y"], "序号为:", 对象结果["id"]
Else
	TracePrint "没有找到任何一个对象喜欢你, 呜呜呜...."
End If


//--------------------正则匹配--------------------//
//元素特征默认是完整匹配, 即大小写与长度都要符合才能找到
//但填入参数-2后将切换至正则匹配模式, 需注意这里使用的是Lua的正则规则
//一般不推荐新手使用该方法, 但这里提供几种简易的规则供大家模仿
// ^紫猫.* 这个规则表示匹配由紫猫做开头的元素特征
// .*紫猫$ 这个规则表示匹配由紫猫做结尾的元素特征
// .*紫猫.* 这个规则表示匹配包含紫猫的元素特征
//更多的匹配规则请浏览 https://zimaoxy.com/m/post/pattern-matching/

Dim 正则结果 = zm.ElementFind("^充值.*", -2)
If 正则结果 Then 
	TracePrint "找到元素为:", 正则结果["text"]
Else 
	TracePrint "未找到元素"
End If

备注

  • 关于参数填写顺序说明
    • 本插件所有参数都是可选的, 绝大多数参数对顺序没有要求, 但以下3个参数有顺序要求
    • ( 查找范围, 指定坐标, 超时时间 )
    • 这3个参数均为可选参数, 中间也可以填写其他参数, 但是前后关系不能打乱, 下面举几个例子
    • 正确例子: ( 查找范围, 超时时间), (指定坐标, 元素特征, 超时时间), (查找范围, 元素特征)
    • 错误例子: (超时时间, 查找范围), (查找范围, 超时时间, 指定坐标), (指定坐标, 元素特征, 查找范围)
    • 如果无法理解的话, 建议按照语法说明的参数顺序填写
  • 关于对象参数
    • 对象参数必须从第1个位置开始填写, 并且填写后除了超时时间外的其他普通参数全都忽略
    • 多个对象为 OR 关系, 内部依次循环查找每一个对象, 任何一个被找到则立即返回
    • 当存在多个超时时间时, 仅最大的时间会生效, 限时内会不断查找每一个对象
  • 关于元素特征串
    • 支持抓抓上的text, resource-id, class, package, content-desc
    • 填写数量自定义, 你可以只写1个, 也可以写3个, 甚至都不写或者全都写.
    • 查找时忽略特征名, 只找特征值, 例如你填写了 "微信", 那么有可能找到 text 是 微信 的元素, 或者 content-desc 是 微信 的元素.
    • 查找时要求填写的特征全都要找到才算符合条件, 包括填写空字符串 "", 也会要求找到对应空字符串
    • 两个特征值一样的也会查找, 例如你填写了 "微信", "微信", 那么查找的时候就会去找元素特征里存在两个 微信 的元素
  • 关于最终元素
    • 最终元素是指没有子节点的元素, 也就是抓抓里看到前面没有 + 或 - 的元素
  • 关于旋转横屏坐标处理
  • 需按键精灵V3.5.8以上版本支持本命令
  • V4.2111: 初次加入