三种控件模式API差异
更新: 2026/3/2 字数: 0 字 时长: 0 分钟
无障碍模式（推荐）
基于 Android 无障碍服务（AccessibilityService） 实时获取控件树，响应速度快、稳定性高，适用于绝大多数自动化场景。
HID / 数字助理模式
基于 AssistService 辅助服务获取控件树结构，适用于部分系统限制无障碍权限的设备环境，相对无障碍模式更安全，常常配合 HID 外置触控硬件一起使用。
ADB Shell / Root 模式（XML 解析）
通过 系统布局层级导出并解析 XML 获取控件树结构，适用于无障碍受限或 Root 设备的高级调试场景。
Selector 选择器差异
👉 选择器语法与大部分 API 完全一致 👉 默认使用 无障碍模式
可通过 selector(mode) 显式指定模式：
无障碍模式（默认模式）
js
// 不加 selector，默认无障碍模式
text("任务管理").findOne();
// 或者显式写 0
selector().text("任务管理").findOne();HID / 数字助理模式
js
// selector(1) 表示 HID / 数字助理模式
selector(1).text("任务管理").findOne();ADB Shell / XML 解析模式
js
// selector(2) 表示 ADB Shell / XML 解析模式
selector(2).text("任务管理").findOne();模式编号说明
| 模式编号 | 模式名称 | 说明 |
|---|---|---|
0（默认） | 无障碍模式 | 实时控件树，推荐使用 |
1 | HID / 数字助理 | AssistService 获取 |
2 | ADB/XML 模式 | 系统布局解析 |
示例
无障碍模式 查找控件
js
// var uiObject = text("任务管理").className("android.widget.TextView").visibleToUser(true).findOne(1000);
var uiObject = selector().text("任务管理").className("android.widget.TextView").visibleToUser(true).findOne(1000);
if (uiObject) {
console.log(uiObject);
} else {
toastLog("未找到符合条件的控件");
}HID / 数字助理模式 查找控件
js
var uiObject = selector(1).text("任务管理").className("android.widget.TextView").visibleToUser(true).findOne(1000);
if (uiObject) {
console.log(uiObject);
} else {
toastLog("未找到符合条件的控件");
}ADB/XML 模式 查找控件
js
var uiObject = selector(2).text("任务管理").className("android.widget.TextView").visibleToUser(true).findOne(1000);
if (uiObject) {
console.log(uiObject);
} else {
toastLog("未找到符合条件的控件");
}Selector 附加选择条件差异
| 选择器条件 API | 无障碍模式 | HID / 数字助理模式 | ADB / XML 模式 |
|---|---|---|---|
| UiSelector.algorithm(algorithm) | ✅ | ❌不支持 | ❌不支持 |
| UiSelector.text(str) | ✅ | ✅ | ✅ |
| UiSelector.textContains(str) | ✅ | ✅ | ✅ |
| UiSelector.textStartsWith(prefix) | ✅ | ✅ | ✅ |
| UiSelector.textEndsWith(suffix) | ✅ | ✅ | ✅ |
| UiSelector.textMatches(reg) | ✅ | ✅ | ✅ |
| UiSelector.desc(str) | ✅ | ✅ | ✅ |
| UiSelector.descContains(str) | ✅ | ✅ | ✅ |
| UiSelector.descStartsWith(prefix) | ✅ | ✅ | ✅ |
| UiSelector.descEndsWith(suffix) | ✅ | ✅ | ✅ |
| UiSelector.descMatches(reg) | ✅ | ✅ | ✅ |
| UiSelector.id(resId) | ✅ | ✅ | ✅ |
| UiSelector.idContains(str) | ✅ | ✅ | ✅ |
| UiSelector.idStartsWith(prefix) | ✅ | ✅ | ✅ |
| UiSelector.idEndsWith(suffix) | ✅ | ✅ | ✅ |
| UiSelector.idMatches(reg) | ✅ | ✅ | ✅ |
| UiSelector.className(str) | ✅ | ✅ | ✅ |
| UiSelector.classNameContains(str) | ✅ | ✅ | ✅ |
| UiSelector.classNameStartsWith(prefix) | ✅ | ✅ | ✅ |
| UiSelector.classNameEndsWith(suffix) | ✅ | ✅ | ✅ |
| UiSelector.classNameMatches(reg) | ✅ | ✅ | ✅ |
| UiSelector.packageName(str) | ✅ | ✅ | ✅ |
| UiSelector.packageNameContains(str) | ✅ | ✅ | ✅ |
| UiSelector.packageNameStartsWith(prefix) | ✅ | ✅ | ✅ |
| UiSelector.packageNameEndsWith(suffix) | ✅ | ✅ | ✅ |
| UiSelector.packageNameMatches(reg) | ✅ | ✅ | ✅ |
| UiSelector.bounds(left, top, right, bottom) | ✅ | ✅ | ✅ |
| UiSelector.boundsInside(left, top, right, bottom) | ✅ | ✅ | ✅ |
| UiSelector.boundsContains(left, top, right, bottom) | ✅ | ✅ | ✅ |
| UiSelector.drawingOrder(order) | ✅ | ✅ | ✅ |
| UiSelector.visibleToUser([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.clickable([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.longClickable([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.checkable([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.selected([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.enabled([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.scrollable([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.editable([b = true]) | ✅ | ✅ | ✅ |
| UiSelector.multiLine([b = true]) | ✅ | ❌不支持 | ❌不支持 |
| UiSelector.findOne() | ✅ | ✅ | ✅ |
| UiSelector.findOne(timeout) | ✅ | ✅ | ✅ |
| UiSelector.findOnce() | ✅ | ✅ | ✅ |
| UiSelector.findOnce(i) | ✅ | ✅ | ✅ |
| UiSelector.find() | ✅ | ✅ | ✅ |
| UiSelector.untilFind() | ✅ | ✅ | ✅ |
| UiSelector.exists() | ✅ | ✅ | ✅ |
| UiSelector.waitFor() | ✅ | ✅ | ✅ |
| UiSelector.filter(f) | ✅ | ✅ | ✅ |
注释说明
- ✅ 代表此模式下支持该选择器条件
- ❌ 代表此模式下不支持该选择器条件
UiObject 控件差异
| UiObject 方法 | 无障碍模式 | HID / 数字助理模式 | ADB / XML 模式 |
|---|---|---|---|
| UiObject.click() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.clickCenter() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.longClick() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.setText(text) | ✅ | ⚠通过$input | ⚠通过$input |
| UiObject.copy() | ✅ | ⚠通过$input | ⚠通过$input |
| UiObject.cut() | ✅ | ⚠通过$input | ⚠通过$input |
| UiObject.paste() | ✅ | ⚠通过$input | ⚠通过$input |
| UiObject.setSelection(start, end) | ✅ | ⚠通过$input | ⚠通过$input |
| UiObject.select() | ✅ | ❌不支持 | ❌不支持 |
| UiObject.collapse() | ✅ | ❌不支持 | ❌不支持 |
| UiObject.expand() | ✅ | ❌不支持 | ❌不支持 |
| UiObject.show() | ✅ | ❌不支持 | ❌不支持 |
| UiObject.scrollForward() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.scrollBackward() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.scrollUp() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.scrollDown() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.scrollLeft() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.scrollRight() | ✅ | ⚠通过$hid | ⚠通过$shellHttp |
| UiObject.children() | ✅ | ✅ | ✅ |
| UiObject.childCount() | ✅ | ✅ | ✅ |
| UiObject.child(i) | ✅ | ✅ | ✅ |
| UiObject.parent() | ✅ | ✅ | ✅ |
| UiObject.bounds() | ✅ | ✅ | ✅ |
| UiObject.boundsInParent() | ✅ | ✅ | ✅ |
| UiObject.drawingOrder() | ✅ | ✅ | ✅ |
| UiObject.id() | ✅ | ✅ | ✅ |
| UiObject.text() | ✅ | ✅ | ✅ |
| UiObject.findByText(str) | ✅ | ✅ | ✅ |
| UiObject.findOne(selector) | ✅ | ✅指定selector(1) | ✅指定selector(2) |
| UiObject.find(selector) | ✅ | ✅指定selector(1) | ✅指定selector(2) |
注释说明
- ✅ 代表此模式下支持此方法
- ⚠ 代表此模式下通过其他模块下的 API 代替此方法
- ❌ 代表此模式下不支持此方法
总结
- HID / 数字助理模式 和 ADB / XML 模式 不能对控件直接点击、长按、滑动、输入、拷贝等操作，只能依赖其他模块里的API来实现
示例
无障碍模式 查找控件并点击
js
var uiObject = selector().desc("任务管理").className("android.widget.LinearLayout").visibleToUser(true).clickable(true).enabled(true).findOne(1000);
if (uiObject) {
var success = uiObject.click();
console.log("click:" + success);
} else {
toastLog("未找到符合条件的控件");
}HID / 数字助理模式 查找控件并点击
js
var uiObject = selector(1).text("任务管理").className("android.widget.TextView").visibleToUser(true).findOne(1000);
if (uiObject) {
//我这里用ESP32的S2开发板进行触控点击中心点坐标
$hid.esp32otg.click(uiObject.bounds().centerX(), uiObject.bounds().centerY());
sleep(1000);
} else {
toastLog("未找到符合条件的控件");
}ADB/XML 模式 查找控件并点击
js
var uiObject = selector(1).desc("任务管理").className("android.widget.LinearLayout").visibleToUser(true).clickable(true).enabled(true).findOne(1000);
if (uiObject) {
//我这里用 $shellHttp 模块进行触控点击中心点坐标
$shellHttp.click(uiObject.bounds().centerX(), uiObject.bounds().centerY());
sleep(1000);
} else {
toastLog("未找到符合条件的控件");
}UiCollection 控件集合差异
| UiCollection 方法 | 无障碍模式 | HID / 数字助理模式 | ADB / XML 模式 |
|---|---|---|---|
| UiCollection.size() | ✅ | ✅ | ✅ |
| UiCollection.get(i) | ✅ | ✅ | ✅ |
| UiCollection.each(func) | ✅ | ❌弃用 | ❌弃用 |
| UiCollection.empty() | ✅ | ✅ | ✅ |
| UiCollection.nonEmpty() | ✅ | ✅ | ✅ |
| UiCollection.find(selector) | ✅ | ✅ | ✅ |
| UiCollection.findOne(selector) | ✅ | ✅ | ✅ |
- ✅ 代表此模式下支持此方法
- ❌ 代表此模式下不支持此方法
代码自动生成
Bot.js Pro和云控后台的在线开发工具均支持控件节点的代码自动生成，你只需要选择对应的参数即可