跳转到内容

数字助理事件

EasyClick 安卓数字助理:用于读取界面节点(找节点 / dumpXml)和截图。数字助理本身不能执行点击、滑动等动作。

推荐用法

日常开发不必改成调用本页的 assistEvent.*,继续用原来的全局写法即可,例如:

  • getOneNodeInfo / getNodeInfo / dumpXml / lockNode / releaseNode
  • 选择器:text("设置").getOneNodeInfo(3000) 等

只需在 App 系统设置里把本应用设为默认数字助理(设置页可跳转系统「数字助理」界面)。服务真正绑定后,上述读节点类 API 会自动优先走数字助理。

  • 不需要为了读节点去开无障碍模式
  • 不需要为了读节点去开代理模式
  • 点击 / 滑动 / 按键等动作:数字助理做不了,请用 蓝牙 HID、OTG HID(或其它已有动作通道)代替无障碍/代理点击

示意:

function main() {
// 1) 先确认数字助理已就绪(默认助理 + 已绑定 + 有过有效数据)
if (!isAssistReady()) {
openAssistSetting();
toast("请设为默认数字助理后再试");
return;
}
// 2) App 设置里已设为默认数字助理即可,脚本仍用原来的找节点写法
var n = text("设置").getOneNodeInfo(5000);
if (n == null) {
toast("未找到节点");
return;
}
logd(n.clz + " " + JSON.stringify(n.bounds));
// 3) 动作不要指望数字助理:用 HID 等执行点击(示例,按你实际 HID 模块调用)
// blehid / otghid 等点击接口,把 n.bounds 中心点传进去
}
main();

引导设置可用:openAssistSetting() / ui.openAssistSetting() / ec.openAssistSetting()。
也可在 EC App 系统设置 → 数字助理设置 → 设置为数字助理 一键跳转。

各机型打开「默认数字助理」路径

不同品牌菜单名称可能略有差异(数字助理 / 助理应用 / 辅助应用 / 语音助手)。找不到时可在系统设置顶部搜索「助理」或「数字助理」。

品牌 / 系统入口路径(参考)
原生 Android / Google Pixel设置 → 应用 → 默认应用 → 数字助理应用
小米 / Redmi / POCO(MIUI / HyperOS)设置 → 应用设置 → 默认应用 → 数字助理
或:设置 → 更多设置 → 无障碍 → 默认应用 → 数字助理
华为(EMUI / HarmonyOS)设置 → 应用和服务 → 默认应用 → 数字助理 / 助理应用
或:设置 → 系统和更新 → 默认应用 → 数字助理
荣耀(MagicOS)设置 → 应用和服务 → 默认应用 → 数字助理 / 助理应用
OPPO / OnePlus / realme(ColorOS / OxygenOS)设置 → 应用 → 默认应用 → 数字助理应用
或:设置 → 应用管理 → 默认应用 → 数字助理应用
vivo / iQOO(OriginOS / Funtouch)设置 → 应用与权限 → 默认应用 → 数字助理应用
部分机型默认应用里可能不显示,可进「辅助应用 / 语音助手」或系统搜索「助理」
三星(One UI)设置 → 应用程序 → 选择默认应用程序 → 数字助理应用

说明:

  • 选中本 App(EasyClick / 你的定制包名)为默认数字助理后,回到 EC 设置页勾选状态会同步;建议点一次「测试节点和截图」。
  • 部分机型(尤其华为)勾选后若读节点仍未走助理,可能是系统未真正绑定 VoiceInteraction,可在设置里关掉再重新选一次。
  • 设为默认后,厂商自带助手(小爱 / 小艺 / 小布 / Bixby 等)的快捷唤起可能被占用或需另行配置,属系统行为。

状态与引导

isDefault 是否设置为数字助理

  • 适配EC 安卓12.9.0+

  • 是否已是系统当前默认数字助理(与设置页勾选一致)

  • @return {boolean}

function main() {
logd("isDefault: " + assistEvent.isDefault());
}
main();

isBound 助理服务是否已绑定

  • 适配EC 安卓12.9.0+

  • 数字助理服务是否已绑定

  • @return {boolean}

function main() {
logd("isBound: " + assistEvent.isBound());
}
main();

isReady 助理是否就绪

  • 适配EC 安卓12.9.0+

  • 默认助理 + 服务已绑定 + 有过有效数据

  • @return {boolean}

function main() {
if (!assistEvent.isReady()) {
openAssistSetting();
toast("请设为默认数字助理后再试");
return;
}
logd("ready");
}
main();

请求画面与dump动作

requestCapture 主动请求画面

  • 适配EC 安卓12.9.0+

  • 主动拉取一帧协助结构 + 截图

  • @param timeout 超时毫秒,默认 2000

  • @return {string} JSON 字符串,含 success / costMs / nodeCount / message

function main() {
var r = assistEvent.requestCapture(3000);
logd(r);
}
main();

dumpXml 获取节点XML

  • 适配EC 安卓12.9.0+

  • 将当前界面节点变成 XML(字段名对齐无障碍 dump:clz / pkg / childCount 等)

  • @return {null|string}

function main() {
assistEvent.requestCapture(2000);
var xml = assistEvent.dumpXml();
logd(xml);
}
main();

dumpXmlFresh 先刷新再 dump

  • 适配EC 安卓12.9.0+

  • 先刷新再 dumpXml

  • @param timeout 超时毫秒,默认 2000

  • @return {null|string}

function main() {
var xml = assistEvent.dumpXmlFresh(3000);
logd(xml);
}
main();

查找节点

getNodeInfo 查找多个节点

  • 适配EC 安卓12.9.0+

  • 按选择器查找多个节点

  • @param selectors 选择器(与全局一致,如 text("设置") 或 JSON)

  • @param timeout 等待毫秒,默认 10000

  • @return {null|NodeInfo[]}

function main() {
assistEvent.requestCapture(2000);
var list = assistEvent.getNodeInfo(text("设置"), 5000);
logd(JSON.stringify(list));
}
main();

getOneNodeInfo 查找一个节点

  • 适配EC 安卓12.9.0+

  • 按选择器查找一个节点

  • @param selectors 选择器

  • @param timeout 等待毫秒,默认 10000

  • @return {null|NodeInfo}

function main() {
assistEvent.requestCapture(2000);
var n = assistEvent.getOneNodeInfo(text("设置"), 5000);
if (n) {
logd(n.clz + " " + JSON.stringify(n.bounds));
// 数字助理不能执行动作;点击请用蓝牙 HID / OTG HID 等
}
}
main();

getNodeInfoForNode 在子树中查找多个

  • 适配EC 安卓12.9.0+

  • @param nid 父节点 nid

  • @param selectors 选择器

  • @param timeout 等待毫秒

  • @return {null|NodeInfo[]}

function main() {
var root = assistEvent.getOneNodeInfo(clz("android.widget.FrameLayout"), 3000);
if (!root) {
return;
}
var kids = assistEvent.getNodeInfoForNode(root.nid, textMatch(".*"), 3000);
logd("count: " + (kids ? kids.length : 0));
}
main();

getOneNodeInfoForNode 在子树中查找一个

  • 适配EC 安卓12.9.0+

  • @param nid 父节点 nid

  • @param selectors 选择器

  • @param timeout 等待毫秒

  • @return {null|NodeInfo}

function main() {
var root = assistEvent.getOneNodeInfo(clz("android.widget.FrameLayout"), 3000);
if (!root) {
return;
}
var n = assistEvent.getOneNodeInfoForNode(root.nid, text("设置"), 3000);
logd(n);
}
main();

节点关系

getNodeInfoParent 父节点

  • 适配EC 安卓12.9.0+

  • @param nid 节点 nid

  • @return {null|NodeInfo}

function main() {
var n = assistEvent.getOneNodeInfo(text("设置"), 3000);
if (n) {
logd(assistEvent.getNodeInfoParent(n.nid));
}
}
main();

getNodeInfoChild 第 index 个子节点

  • 适配EC 安卓12.9.0+

  • @param nid 父节点 nid

  • @param index 子节点下标,从 0 开始

  • @return {null|NodeInfo}

function main() {
var n = assistEvent.getOneNodeInfo(clz("android.widget.LinearLayout"), 3000);
if (n) {
logd(assistEvent.getNodeInfoChild(n.nid, 0));
}
}
main();

getNodeInfoAllChildren 全部子节点

  • 适配EC 安卓12.9.0+

  • @param nid 父节点 nid

  • @return {null|NodeInfo[]}

function main() {
var n = assistEvent.getOneNodeInfo(clz("android.widget.LinearLayout"), 3000);
if (n) {
logd(assistEvent.getNodeInfoAllChildren(n.nid));
}
}
main();

截图

captureFullScreen 截图

  • 适配EC 安卓12.9.0+

  • 拉取截图,返回 AutoImage;失败返回 null(不回退其它截屏通道)

  • @return {null|AutoImage}

function main() {
var img = assistEvent.captureFullScreen();
if (img) {
logd("w=" + img.getWidth() + " h=" + img.getHeight());
img.recycle();
} else {
toast("截图失败");
}
}
main();

锁定节点

lockNode 锁定节点

  • 适配EC 安卓12.9.0+

  • 锁定当前节点缓存

  • 可先 requestCapture,否则返回 false

  • 需与 releaseNode 配合

  • @return {boolean}

function main() {
assistEvent.requestCapture(2000);
assistEvent.lockNode();
for (var i = 0; i < 5; i++) {
logd(assistEvent.getOneNodeInfo(text("设置"), 1000));
}
assistEvent.releaseNode();
}
main();

releaseNode 释放节点锁

  • 适配EC 安卓12.9.0+

  • 释放后,后续可更新节点树

  • @return {boolean}

function main() {
assistEvent.releaseNode();
}
main();

相关全局 / UI 函数

  • 适配EC 安卓12.9.0+

设为默认助理、状态查询也可在脚本全局或 UI / H5 中调用:

场景函数
脚本全局openAssistSetting() / isAssistDefault() / isAssistReady()
原生 UI(ui)ui.openAssistSetting() / ui.isAssistDefault() / ui.isAssistReady()
H5 UI(ec)ec.openAssistSetting() / ec.isAssistDefault() / ec.isAssistReady()

详见 全局模块、JS与UI交互、H5 UI编写。