Hamibot 控件选择器 UiSelector 基础
控件 vs 坐标
安卓界面上的按钮、文本框、列表项等都是「控件」。基于控件的操作指的是：
- 用选择器定位到某个控件（按 id、文本、类型等属性）
- 获取控件信息或对其操作（点击、长按、输入等）
这种方式的好处是不依赖屏幕分辨率——无论在什么尺寸的设备上运行，只要控件属性匹配就能找到。相比之下，基于坐标的点击在不同分辨率设备上需要做适配。
auto 系列函数
控件操作依赖无障碍服务，脚本开头通常会调用 auto() 系列函数来确保服务已启用：
| 函数 | 行为 |
|---|---|
auto() | 检查无障碍是否已启用，没启用则跳转系统设置页并中止脚本 |
auto.waitFor() | 检查无障碍，没启用则跳转并等待用户开启后自动继续 |
auto('fast') | 启用快速模式（开启控件缓存，定位更快） |
auto.setMode('fast') | 切换模式，不触发权限检查 |
推荐用 auto.waitFor()——用户开启无障碍后脚本会自动接着跑，体验更流畅。
选择器基础用法
Hamibot 兼容 AutoJS 的 id()、text()、desc()、className()、bounds() 等选择器。常用模式：
按 resource-id 选择
每个控件通常有一个唯一的 id（由开发者在写 APP 时定义）。这是最稳定的选择方式：
// 找到 id 为 "btn_submit" 的按钮
id("btn_submit").findOne().click();按文本选择
// 找到文本为 "确定" 的控件
text("确定").findOne().click();
// 包含某段文字
textContains("下一步").findOne().click();
// 正则匹配
textMatches("提交.*").findOne().click();按描述选择
部分控件有 contentDescription（无障碍描述），可以用 desc() / descContains() / descMatches()。
按控件类型 + 组合
// 找到第一个按钮类型的控件
className("android.widget.Button").findOne().click();
// 组合条件：id 存在 AND 文本包含
id("submit").textContains("提交").findOne().click();查找函数
选择器链末尾加的查找函数决定行为：
| 函数 | 行为 | 适用场景 |
|---|---|---|
findOne() | 找到第一个匹配的控件，没找到会阻塞等待（默认超时 10 秒） | 确定控件一定会出现 |
findOne(5000) | 同上，自定义超时 5 秒 | 需要调整等待时间 |
findOnce() | 立即查找，没找到返回 null 不阻塞 | 不确定是否出现，配合条件判断 |
find() | 查找所有匹配的控件 | 需要遍历列表 |
控件操作方法
找到控件后可以调用这些方法：
| 方法 | 效果 |
|---|---|
.click() | 点击控件（如果 clickable） |
.longClick() | 长按 |
.setText("hello") | 输入文本（输入框） |
.scrollForward() / .scrollBackward() | 列表滚动 |
.bounds() | 获取位置坐标 Rect |
.text() / .desc() | 获取控件文本或描述 |
典型脚本示例
一个简单的自动点击脚本结构：
auto.waitFor();
// 打开目标 APP
app.launch("com.example.app");
// 等待控件出现并点击
const btn = text("开始").findOne();
btn.click();
// 然后继续下一步
sleep(1000);何时不用控件选择器
有些界面没有可识别的控件（比如游戏画面），这时要用坐标操作。详见「坐标触摸与手势」。