做uni-app开发这几年最让我头疼的一件事就是App里要做批量操作、自动填写表单、一键完成某个重复流程时前端代码根本够不着Android系统的控件树。你翻遍Vue组件和H5 API都找不到一个能帮你“点一下”、“填一下”、“翻一页”的能力。后来我陆续尝试了几种方案终于把目标锁定在无障碍服务AccessibilityService上又在插件市场淘到了lqy-accessibility这个基于UTS封装的无障碍服务插件。简单说lqy-accessibility就是给uni-app App端插上了一只“眼睛”和一只“手”它能读取当前界面的控件节点按文本、ID、类名找到目标元素然后帮你执行点击、长按、输入文字、滑动、返回等一系列操作。对做自动化辅助工具、内部效率工具、自动测试脚本的人来说这基本属于“刚需神器”。这篇文章我会从原理讲到底层机制再一步步展示引入、授权、找节点、做自动化操作的全过程顺便把我踩过的坑全部摊开。如果你只是听说过无障碍自动化、想在uni-app项目里跑通一次真正的自动化流程或者正在纠结“这东西到底上不上得了台面”那这篇内容正好适合你。不管你是写业务的前端还是搞测试脚本的工程效率团队按下面的思路操作至少能少走两三个月的弯路。1. 为什么需要这么一款“自动化神器”1.1 先搞懂无障碍服务到底能干什么Android的无障碍服务最初是为了帮助视障、肢体不便的用户设计的系统级辅助工具。它运行在系统进程里可以向系统注册自己感兴趣的事件比如窗口状态变化、控件焦点变化、视图点击等。系统发现这些事件后会把带着节点信息的AccessibilityEvent交给无障碍服务服务再从窗口的控件树里读取页面结构。听起来是个辅助功能但它能干的事情可不只是“朗读屏幕”。无障碍服务本质上获得了三块关键能力一是读取能力可以遍历当前界面的节点树拿到控件的文本、ID、类名、坐标、是否可点击、是否选中这些属性二是操作能力可以模拟用户手指点击、长按、滑动、手势也可以给输入框设置文本三是全局能力通过全局操作还能实现返回键、Home键、最近任务键、下拉通知栏等系统级动作。对我这种做uni-app的开发者来说这简直是把“真机自动化”的能力从原生层搬到了前端可调度的程度。以前我们需要靠肉眼去点、去滑现在可以写代码让App自己去点、自己去滑。lqy-accessibility这类UTS插件就是把这些系统能力封装成uni-app前端能直接调用的JS接口。1.2 UTS插件比传统原生插件好在哪接触过uni-app原生插件开发的人应该深有体会以前要接入一个无障碍服务要么自己用Android Studio写原生插件事件监听、节点遍历、JS回调、bridge逻辑一个都不能少写完之后还得打包成Android原生插件包上传到插件市场或者走本地打包然后前端再通过uni.requireNativePlugin去调用链路长、门槛高出了问题光排查原生日志就要花半天。UTS插件的出现改变了这个玩法。UTS是DCloud推出的一种基于TypeScript语法扩展的“全能语言”写在uni-app项目里的UTS代码经过编译后可以直接运行在Android和iOS原生层。也就是说写UTS插件只需要掌握TypeScript语法基础就可以在uni-app项目里原生操作AccessibilityService、Intent、PackageManager这些系统API而不是再去维护一整套独立的Android工程。lqy-accessibility走的就是这条路线。同一套代码里你既能用Vue写页面又能在需要时掉到底层调用系统无障碍服务。对比传统方案优势非常明显打包更简单云端打包就能完成原生代码的编译不需要本地Android Studio环境调用链路更短前端直接通过requireNativePlugin拿到插件实例然后像调用普通对象方法一样调用无障碍接口调试成本低纯JS/TS层报错能直接看到逻辑问题只是涉及原生底层的报错要回看Logcat。1.3 它和自动化测试框架的区别很多人会把它和Appium、Playwright这类自动化测试框架搞混以为装了插件就能直接做全套自动化测试。实际定位是不同的。Appium是独立的服务器架构通过WebDriver协议驱动设备适合做无侵入的、偏向黑盒的外部自动化比如用例回归、跨端测试平台Playwright则专攻Web/H5端更依赖浏览器的调试协议。lqy-accessibility是App内部的无障碍服务方案。它在App运行时就驻留在系统辅助功能列表里适合做和业务强耦合的自动化操作表格批量填写、导入导出流程的自动导航、定时提醒后的自动打开页面、连点器类的辅助工具、针对自有App的智能助手。它不需要额外的服务端也不依赖PC连接一台手机全搞定。选择哪种方案取决于你的目标。如果你关注的是“在真机上一键自动完成某个功能流程”而且这份自动化能力就长在你的uni-app应用里那么无障碍服务UTS插件是更轻、更直接的选择。2. 核心原理解析无障碍服务怎么和uni-app写在一起2.1 无障碍服务在Android系统里的运行机制要理解lqy-accessibility就得先理解无障碍服务在系统里是怎么跑起来的。通常一个无障碍服务需要三个要素配合继承AccessibilityService的Service类、描述服务配置的XML文件、AndroidManifest里的声明和权限配置。系统根据这段声明把这个服务注册进无障碍服务列表等用户在系统设置里手动开启之后AccessibilityService的生命周期才正式启动。服务开启后系统会对它发出窗口内容变化的回调你可以在onAccessibilityEvent里拿到根节点然后向下遍历整个控件树。每个AccessibilityNodeInfo就代表一个界面上的节点它既可以是类似Button的独立控件也可以是一个装载子控件的ViewGroup。节点的结构大概像一棵倒挂的树你在代码里findByText本质上就是从根节点出发做一次深度优先搜索找到文本内容匹配的目标节点。这里有一个很关键的机制无障碍服务拿到的不是App内部的内存对象而是系统为用户提供的一套“界面镜像”。打个比方就像系统给无障碍服务递了一张屏幕的“透视图”透过这张图你既能看到按钮的位置也能对它做出模拟操作。正因为是镜像你无法直接访问另外一个App的内存数据只能在界面层做操作。这也是为什么无障碍服务经常被称为“看得见的手”它不越界也不需要越界。2.2 UTS如何把原生能力暴露给前端UTS插件向uni-app前端暴露能力本质上是把原生对象方法映射成一个前端可以调用的模块。你在uni-app代码里执行uni.requireNativePlugin(lqy-accessibility)时前端框架会去原生层找到这个名字对应的UTS插件模块然后返回一个对象实例。接下来你调用的每个方法经过UTS编译层的桥接直接执行的是原生层逻辑。拿查找节点来举例。前端调用findByText(登录)UTS插件内部会去获取当前窗口根节点再递归遍历整棵节点树比对每个节点的text属性是否包含“登录”关键字结果可能是零个、一个或者多个最终通过Promise或回调返回到前端。这个流程里节点查找、事件权限判断、主线程与UI线程切换这些脏活累活都在UTS层完成。正因为UTS可以直接操作Android原生API无障碍服务场景才能被完整包裹起来。如果是纯前端实现你连获取系统窗口权限的入口都没有如果完全走原生插件维护成本和隔离感又很重。UTS卡在中间这个生态位上很好的兼顾了开发效率和底层能力。2.3 授权环节绕不开的一道门槛无障碍服务不是装了就能用。用户必须进入系统设置找到“无障碍”或“辅助功能”入口手动找到你的应用服务项并开启开关。这是Android系统的安全设计目的就是避免任何App在后台静默获得这种“指挥手机”的权力。从开发角度看要想确认服务是否真正可用一般有两个判断路径一是直接调用系统无障碍服务相关的API查询启用状态也就是插件里的isServiceRunning / isAccessibilityEnabled这类方法二是当你主动去查询服务状态却拿到“未开启”结果时需要弹出引导弹窗或直接跳转到无障碍设置页让用户手动打开。我在实际项目里通常会在App首页做一个状态卡片开启状态显示绿色并允许业务进入自动化流程未开启就展示高亮提示按钮点击后跳转无障碍设置界面。这样既完成了权限引导也避免了用户因为找不到入口而弃用。注意跳转无障碍设置需要用到android.provider.Settings里ACTION_ACCESSIBILITY_SETTINGS这个动作同样由UTS插件封装好前端一行代码就能唤起。提示无论插件API叫什么都要记住一件事无障碍服务的授权状态必须动态检测不能在启动时假设它就绪因为用户完全可能清理后台、重启手机之后把开关关了。3. 实操从安装到完成第一次自动化操作3.1 获取与引入插件以及在manifest中的配置lqy-accessibility一般通过HBuilderX的插件市场获取在插件市场搜索插件名点击“使用”并选择绑定到当前项目即可。插件安装完成后需要在项目的manifest.json里做一些配置核心是App模块配置和原生插件声明。打开manifest.json切到“App原生插件配置”确认已添加lqy-accessibility并且勾选对应的Android平台支持。这里有一个容易踩的坑UTS插件在HBuilderX里有内置插件和云端插件两种形态。lqy-accessibility通常属于云打包插件也就是不需要你本地打包直接在云打包时自动拉取插件代码编进App里。但正因为是云打包首次集成后建议先打一次自定义调试基座再在真机上运行不要直接使用标准基座因为你项目里没有声明这个插件时标准基座不会带上它。manifest里的另外一个细节是权限。无障碍服务插件一般会在插件的原生清单里自动声明BIND_ACCESSIBILITY_SERVICE权限这类特殊权限在Manifest里表现形式是service标签加android:permissionandroid.permission.BIND_ACCESSIBILITY_SERVICE并配合accessibilityEventTypes和accessibilityFeedbackType等meta-data。正常流程下你不用手改这些但一旦发现真机服务列表里找不到你的应用优先检查插件版本和基座是否一致。3.2 启动服务与授权检测的完整流程一旦插件引入成功第一件要做的事情就是封装一个全局的工具类。我习惯在项目的utils目录下新建一个accessibilityHelper.js把插件的生命周期管理统一收拢到一个模块避免业务代码里到处requireNativePlugin然后直接操作原生对象。第一次启动时通过uni.requireNativePlugin(lqy-accessibility)获取插件实例注意这个方法的入参是插件在前端注册时的标识名不要拼错。拿到实例后先调用插件暴露的状态查询方法通常会返回类似res.running、res.enabled这样的布尔值字段。如果未开启就调用跳转到无障碍设置页的方法如果已开启再调用startService或者listen方法告诉插件开始关注窗口变化事件。授权流程代码结构大致是下面这样// utils/accessibilityHelper.js const LQY_PLUGIN lqy-accessibility; function getPlugin() { return uni.requireNativePlugin(LQY_PLUGIN); } function checkAndStart() { const plugin getPlugin(); const status plugin.isServiceRunning(); if (status status.running) { // 已经在运行直接返回当前状态 return Promise.resolve(true); } // 未运行尝试拉起到无障碍设置页 plugin.openAccessibilitySettings(); return Promise.resolve(false); } function getCurrentNodeInfo() { const plugin getPlugin(); return plugin.getRootNode ? plugin.getRootNode() : null; }把这段代码放到App启动后的一个引导流程里就可以做到用户点“开启自动化”按钮先检查授权状态未授权就跳设置页授权回来后重新查询并继续执行后续动作。我这里给出的API命名是这类插件里比较通用的设计具体字段名要以你下载插件版本的文档为准。关键是这个流程检测、跳转、回读、继续。3.3 常用API与第一段自动化代码跑通授权之后就可以体验自动化的核心能力了。lqy-accessibility最常用的接口大概集中在几类查找节点、执行点击、输入文本、滑动页面、全局操作。下面我按项目里出现频率最高的场景列一下具体实现思路以通用UTS无障碍插件为参考。第一类查找节点。最常用的是按文本找比如findByText(立即登录)返回第一个匹配的节点信息还有findByTextContains(登录)用来做模糊匹配应对按钮文案动态变化的情况以及findById(com.example:id/btn_submit)这种按资源ID精确查找在原生页面里很靠谱但H5和uni-app页面里不一定有资源ID所以文本查找实际使用率更高。第二类执行操作。找到节点不等于能操作很多情况下节点是可点击的我们可以直接在该节点上执行click()。但有时目标节点不是按钮本身只是包裹文字的一个TextView直接点击会无效这时候需要向上回溯找到它的可点击父节点再点击。这个“找最近可点击父节点”的动作特别重要很多新手第一次做自动化失败都卡在这里。第三类输入文本。输入框节点通常有一个ACTION_SET_TEXT的Action插件封装出setText或者inputText方法后我们可以直接往输入框写入内容。注意真实输入流程里焦点和键盘弹出的时序问题建议写入文本后不要立即点击提交按钮留一个300到500毫秒的缓冲否则可能出现内容还没同步到控件的尴尬情况。一个比较典型的自动化场景是自动填写登录表单// 假设页面里有两个输入框和一个登录按钮 const plugin uni.requireNativePlugin(lqy-accessibility); // 1. 查找账号输入框通过Hint文本定位 const accountInput plugin.findByHint(请输入手机号); if (accountInput accountInput.nodeId) { plugin.setText(accountInput.nodeId, 13800138000); } // 2. 查找密码输入框 const pwdInput plugin.findByHint(请输入密码); if (pwdInput pwdInput.nodeId) { plugin.setText(pwdInput.nodeId, 123456); } // 3. 延迟后点击登录按钮 setTimeout(() { const loginBtn plugin.findByText(登录); if (loginBtn) { plugin.clickNode(loginBtn.nodeId); } }, 500);这段逻辑大概覆盖了“找控件、填内容、点按钮”三类核心动作也是你在无障碍自动化里最常碰到的操作组合。真正跑起来之后你会发现脚本写的顺序和人工操作几乎一致差别只是过去用手指现在用节点。4. 进阶场景与关键细节处理4.1 等待节点替代傻等sleep初学者在写自动化脚本时最爱用setTimeout页面跳转等一秒数据加载等两秒。这种方式在慢网络、低端机上非常不靠谱经常出现“按钮还没渲染出来就去找结果找不到”的报错。成熟的实现方式是“轮询等待节点”也就是写一个waitFor方法每隔300毫秒去查找一次目标节点最多尝试N次找到就返回超时就报错。我自己封装的waitForText大概长这样function waitForText(text, timeout 5000) { const plugin uni.requireNativePlugin(lqy-accessibility); const start Date.now(); return new Promise((resolve, reject) { const timer setInterval(() { const node plugin.findByText(text); if (node) { clearInterval(timer); resolve(node); } else if (Date.now() - start timeout) { clearInterval(timer); reject(new Error(等待节点超时: ${text})); } }, 300); }); }轮询比sleep合理的地方在于它把时间开销压缩到最小。页面加载快脚本就能立刻继续页面加载慢它也能等到目标出现为止。配合上系统的无障碍事件通知机制有些UTS插件还会提供onWindowChange回调一旦检测到窗口切换就主动刷新节点缓存。那样做效率更高不过为了兼容性轮询依然是压箱底的通用法。4.2 滑动、翻页与滚动加载的自动化处理很多自动化流程不止是点几个按钮还涉及滑动翻页。lqy-accessibility一般会提供swipe方法入参是起点坐标和终点坐标或者直接传入起始百分比。比如需要向下翻一页可以模拟从屏幕坐标(540, 1200)滑到(540, 500)。但如果屏幕尺寸不同硬编码的坐标点可能失效更好的做法是通过节点查找找到ListView或ScrollView再在该节点的坐标范围内计算一条滑动手势。ScrollView的节点通常很好识别类名里可能带scroll、list、recycler这些关键词或者findByClass(androidx.recyclerview.widget.RecyclerView)。拿到节点的boundsInScreen屏幕上的矩形边界后取中心点和偏移量做滑动基本能适配不同分辨率的屏幕。我试过用坐标硬编码适配单一测试机没问题但后来换了一台平板整个脚本直接罢工那之后所有滑动都改成基于节点bound动态计算稳定性明显提升。滚动加载的长列表场景还要注意一个细节滚动动作之后屏幕上的节点树会被刷新之前保存的nodeId可能会失效。正确做法是每滚动一次就重新查找关键节点或者至少重新获取一次根节点再往下找不要一直持有旧节点引用。4.3 特殊场景WebView、自定义控件与多窗口切换无障碍自动化的世界里并不是所有控件都配合你。页面里套了WebView的时候控件树里的节点粒度变成WebView内部内容是能拿到部分HTML控件映射的但文本节点和行为节点的可操作性不如原生控件稳定。uni-app的H5页面跑在WebView里如果直接findByText“登录”大概率能匹配到但setText对某些HTML输入框的匹配特性比较挑剔可能需要走“先点击输入框再逐个字符输入”的老办法。自定义控件尤其是自己绘制图形的View本身不是一个能响应无障碍Action的标准控件。这种情况下你无法通过节点去执行点击只能退回到坐标点击借助getBoundsInScreen拿它的大致位置或者干脆给自定义控件加上contentDescription属性让它成为一个可被无障碍识别的语义节点。这属于开发侧的配合如果你在给自身App做自动化记得补contentDescription。多窗口、弹窗、Toast这些都是节点查找的干扰项。Toast通知出现时会短暂成为当前活跃窗口如果你代码在Toast弹出瞬间去查找“登录按钮”有可能找到的不是你要的内容。处理方式是增加等待条件确保目标节点可见且在某个关键窗口之上。部分UTS插件会提供窗口类型判断或者getActiveWindowId可以在逻辑里加一层窗口过滤。这个能力属于锦上添花的细节真遇到再做不迟。5. 常见问题排查与避坑实录5.1 授权失败或找不到无障碍入口这大概是所有刚开始用无障碍服务的开发者遇到的第一个“劝退点”。现象是代码里调用openAccessibilitySettings后设置页面能找到别的App但就是找不到自己应用的条目或者成功开启了返回App用isServiceRunning检测还是false。我遇到过的原因大概是这几种第一插件没有真正被编进App里。常见于使用标准基座运行调试或云打包配置里没勾选插件。解决办法是重新生成自定义调试基座或者确认打包时插件列表里有lqy-accessibility。第二插件内部声明的Service有问题。BIND_ACCESSIBILITY_SERVICE权限必须声明并且在Manifest里service标签下要有对应的无障碍配置引用包括accessibilityEventTypes和canPerformGestures等meta-data。这部分一般在插件源码里写好了但如果版本很老、不同ROM兼容性有差异也可能出现部分机型上服务注册失败。第三国产ROM对后台无障碍服务的“杀死”策略很激进。小米、华为等系统会默认限制长期在后台运行的辅助功能服务用户明明开了授权过一阵子又自动失效。应对办法是引导用户把App加入后台白名单、锁定最近任务列表、允许自启动。这些统称为“保活配置”在自动化工具类应用里几乎是标配。5.2 查找节点为空、点击没反应如果授权正常节查找却时常拿不到结果问题大概率出在时序和节点层级上。页面动画还没结束、网络请求还没返回、列表还没渲染都会呈现“暂时性节点缺失”。不要在一个查找失败后就放弃优先使用waitFor包装的多轮查询。点击没反应首先要确认你要点的节点是不是真正可点击的。很多TextView虽然展示为按钮样式但它实际只是一个文本载体可点击的是父级容器。我踩过最典型的一次按钮外层是一个LinearLayout内层TextView显示文案直接click文本节点毫无反应向上找两级的LinearLayout再click一下就触发了。如果你选的插件提供了clickByText之类的高层封装恭喜它能自动向上搜索可点击父节点如果没有就需要自己在UTS层实现一个向上递归找父可点击节点的函数。还有一种情况是节点坐标越界。个别平板和折叠屏上bound坐标系和屏幕实际物理坐标不一致尤其是出现显示缩放时。这种情况下建议清掉获取到的节点坐标做一次clipToScreen保证点击落在有效区域内。5.3 编译问题、后台限制与应用市场上架风险UTS插件的编译问题主要集中在HBuilderX版本和插件版本不匹配上。如果HBuilderX太旧UTS语法和云打包链条都不支持最新插件接口很容易编译报错或打包失败。建议统一升级到最新稳定版并让插件市场和HBuilderX的版本保持同一周期。遇到“UTS编译错误”先在本地把语法问题排掉再考虑是不是插件本身和编译器不兼容。还要提一个很多人容易忽略的点Android从低版本到高版本一直在收紧无障碍服务的后台权限。在Android 10及以上后台弹窗、手势模拟都有额外限制Android 12及以上对“无障碍服务来执行点击”的检测也变严格了部分系统会在顶部常驻一个“正在使用无障碍服务”的提示。这些限制不是安全问题但会影响用户的体验观感开发时要有心理预期。最后说一句上架审核。如果你的应用声明了无障碍服务权限国内市场审核时大概率会被特别询问。很多工具类App、远程协助类App、自动化办公类App确实需要这个能力但前提是在权限声明里把使用场景讲清楚在隐私政策里写明数据采集范围最好做到“不被使用的时候不要常驻服务”。千万不要把无障碍权限用在绕过风控、批量薅羊毛、自动抢单这种灰色路径上。一旦被平台抓取到异常行为特征轻则功能下架重则开发者账号被拉黑。合规使用才能细水长流。6. 我的实践体会开发这半年我把lqy-accessibility用在一个内部台账系统上。过去每天要人工在业务App里翻十几屏、填写几十个字段现在打开App里的自动化面板一键就能把常用数据刷进目标页面。省下来的时间很多更重要的是消除了大量重复操作带来的疲劳感。我个人在实际操作中的深刻体会是无障碍自动化最大的成本从来不是“插件怎么调”而是“节点怎么稳定地找到”。所以我在项目里会刻意给自身应用的所有关键控件加上contentDescription甚至专门把按钮的文本文案固定下来、不加动效、不用跑马灯。这些从源头保证节点可识别的手段比在脚本里写一堆兼容逻辑更省事。最后再分享一个小技巧把插件的所有调用统一封装在utils/accessibilityHelper.js里不要散落在各个页面。以后要替换插件、升级接口、增加统一超时处理都只改一个文件。脚本稳定性的提升虽然不是立竿见影但长期维护下来能帮你省掉大量重复排查的时间。真机上多跑几轮把超时时间、轮询间隔调成一套合适自己业务的参数你会发现这套自动化方案比想象中还要顺手。
