$assistant 与控件树操作

更新: 2026/3/2 字数: 0 字 时长: 0 分钟

$assistant 模块提供类似 Android 无障碍节点树的控件树访问能力，用于在 HID/数字助理模式下获取窗口信息与控件层级结构。

$assistant.waitFor()

检查 AssistService 是否已经连接并启用，如果尚未启动则跳转到辅助服务启用界面，并等待服务启动完成；当 AssistService 启动后脚本将继续执行。

该函数为阻塞调用。

在 UI 模式或不支持阻塞的环境中不建议使用，推荐在普通脚本环境下调用。

示例：

$assistant.waitFor();

$assistant.service

• {AssistService}

获取当前连接的 AssistService 实例。
若服务未启动则返回 null。

var service = $assistant.service;
if (service != null) {
    console.log("AssistService 已启动:", service);
} else {
    console.log("AssistService 未连接");
}

$assistant.openSettings()

跳转到 AssistService（数字助理 / 辅助服务）启用设置界面。

当辅助服务尚未开启时，可通过该函数引导用户进入系统设置页面进行开启。

返回是否成功发起跳转操作。

• 返回 {boolean}

$assistant.openSettings();

$assistant.windows

• {Array}

返回系统当前存在的所有窗口对象数组（包括后台窗口、悬浮窗等）。

示例：

var windows = $assistant.windows;
console.log("窗口数量:", windows.length);

windows.forEach((w, i) => {
    console.log("窗口[" + i + "] 标题:", w.getTitle());
});

$assistant.root

• {UiNode}

返回第一个窗口的控件树根节点。

示例：

var root = $assistant.root;
if (root) {
    console.log("根节点:", root);
    console.log("子节点数量:", root.children().length);
} else {
    console.log("未获取到根节点");
}

$assistant.rootInActiveWindow

• {UiNode}

返回当前活跃窗口的控件树根节点。

var activeRoot = $assistant.rootInActiveWindow;
if (activeRoot) {
    console.log("活跃窗口根节点:", activeRoot);
} else {
    console.log("当前无活跃窗口");
}

$assistant.windowRoots

• {Array}

返回所有被窗口过滤器允许的窗口根节点数组。

var roots = $assistant.windowRoots;
console.log("过滤后窗口数量:", roots.length);

roots.forEach((r, i) => {
    console.log("根节点[" + i + "] 子节点数:", r.children().length);
});

$assistant.setWindowFilter(filterFn)

• filterFn {Function}

设置窗口过滤器函数，用于决定哪些窗口会被纳入控件分析范围。

filterFn(window) 返回 true 表示允许。

示例（全部允许）：

$assistant.setWindowFilter(function (window) {
    console.log("检测窗口:", window.getTitle());
    return true;
});

示例（仅微信窗口）：

$assistant.setWindowFilter(function (window) {
    return window.getTitle().includes("com.tencent.mm");
});

$assistant.currentPackage()

• 返回 {string}

返回最近一次监测到的前台应用包名。

var pkg = $assistant.currentPackage();
console.log("当前应用包名:", pkg);

⚠️ AssistService 未启动时将抛出异常。

$assistant.currentActivity()

返回最近一次监测到的前台 Activity 完整类名。

• 返回 {string}

var act = $assistant.currentActivity();
console.log("当前 Activity:", act);

⚠️ AssistService 未启动时将抛出异常。

$assistant.captureScreen()

使用 AssistService 截图。

• 返回 {Image}

var img = $assistant.captureScreen();

$images.save(img, "/sdcard/capture.png");

$assistant.captureScreen(path)

使用 AssistService 截图并直接保存到指定路径。

• path {string} 保存路径
• 返回 {boolean}

$assistant.captureScreen("/sdcard/capture.png");

$assistant.clearCache()

清空 AssistService 内部的控件节点缓存。

当界面已经发生变化，但通过选择器或控件树仍然获取到旧节点数据时，可调用该函数强制刷新缓存。

在以下场景中推荐使用：

• 页面跳转后无法获取最新控件树
• 动态刷新界面节点未更新
• 节点存在但查找始终失败

示例：

$assistant.clearCache();