zm.ElementFind 超级查找元素

🎯功能

根据条件查找元素节点, 返回元素节点表信息与中心坐标等数据. 比 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" 代表多个对象情况下找到的那个序号

💡示例

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 是 微信 的元素.
- 查找时要求填写的特征全都要找到才算符合条件, 包括填写空字符串 "", 也会要求找到对应空字符串
- 两个特征值一样的也会查找, 例如你填写了 "微信", "微信", 那么查找的时候就会去找元素特征里存在两个 微信 的元素
关于最终元素
- 最终元素是指没有子节点的元素, 也就是抓抓里看到前面没有 + 或 - 的元素
关于旋转横屏坐标处理
- 如果遇到打开某个应用后, 屏幕方向被旋转了, 导致获取元素中心坐标异常时, 请使用 zm.ElementRotation 设置元素旋转方向解决
需按键精灵V3.5.8以上版本支持本命令
V4.2111: 初次加入

🎯功能​

📜语法​

📥参数​

📤返回​

💡示例​

📘备注​

🎯功能

📜语法

📥参数

📤返回

💡示例

📘备注