5.1 KiB
5.1 KiB
手机 RPA 元素拾取与定位标准
先读
RPA_ELEMENT_LOCATING.md。Android 首选 uiautomator2 或 Appium UiAutomator2；iOS 使用 Appium + XCUITest/WebDriverAgent。当前模板尚无团队真实成功案例，因此本文是强制设计标准，example 仅为规格骨架，不得宣称已生产验证。
目录
- 状态与边界
- 设备准备
- 拾取工具和步骤
- Android 定位优先级
- iOS 定位优先级
- Native/WebView 与动态界面
- 手势、输入和等待
- 降级与留证
- example 路由
1. 状态与边界
- Android 标准可用于设计和实现，但交付前必须在授权真机和官方 App 上验证。
- iOS 必须有 Mac、签名可用的 WebDriverAgent 和授权设备。
- 不 Root、不越狱、不 Hook、不修改 APK/IPA、不伪造设备身份。
- 短信、人脸、指纹、系统安全确认交给人工。
2. 设备准备
每次运行前检查：
- 唯一设备 serial/UDID；多个设备时不得默认取第一个。
- USB/网络连接和调试授权。
- Android 包名/Activity，或 iOS bundle id。
- 屏幕是否解锁、方向、分辨率和系统弹窗状态。
- 自动化 driver/service 是否可用。
- 设备租约/互斥；同一设备默认串行。
doctor 应输出上述信息，但不得输出设备隐私数据。
3. 拾取工具和步骤
Android 可使用 Appium Inspector、uiautomator2 的 UIAutoDev/层级导出；iOS 使用 Appium Inspector。
- 在真机上手工进入准确页面。
- 刷新 Inspector screenshot 和 page source。
- 在截图或 XML 树中点选元素。
- 记录：
- Android：resource-id、content-desc、text、class、package、clickable、enabled、bounds
- iOS：name/accessibility id、label、value、type、enabled、visible
- 确认当前 context 是 Native 还是正确 WebView。
- 记录稳定父容器、列表行和业务锚点。
- 在 Inspector 搜索定位器，确认匹配数量。
- 写入 element map，保存 screenshot + XML。
- 重启 App、重新进入页面并复测。
截图上看到的元素不一定存在于控件树；必须以 page source/可访问性树验证，不能直接凭坐标写代码。
4. Android 定位优先级
从高到低：
- 稳定且唯一的
resourceId description/content-desc（accessibility）- 稳定
text + className - 业务父容器内的子元素组合
- UiSelector / 相对关系
- 短 XPath
- 已验证的 instance/index
- 图像/坐标
示例：
search = d(resourceId="com.example:id/search_input")
if search.count != 1:
raise RuntimeError("ERROR:ELEMENT_AMBIGUOUS search_input")
search.click()
search.set_text(keyword)
if not d(resourceId="com.example:id/result_list").wait(timeout=10):
raise RuntimeError("ERROR:RESULT_TIMEOUT")
第三方 App 没有 resource-id 时，使用可访问性描述、稳定文案和父容器组合；不得修改第三方 APK 添加 id。
5. iOS 定位优先级
从高到低：
- accessibility id / name
type + name/label/value- iOS predicate string
- iOS class chain
- XPath
- 图像/坐标
XPath 依赖完整 XML 且通常较慢，只作后备。多个同名按钮时先定位 navigation bar、cell、alert 或其他业务容器。
6. Native/WebView 与动态界面
Native/WebView
- 先枚举 contexts。
- Native 元素使用移动端控件树。
- WebView 元素切换到正确 web context 后使用 Web 定位器。
- context 数量或名称变化时按包名、URL或页面特征验证，不默认取第一个 WebView。
动态列表
- 虚拟列表只暴露屏幕附近元素。
- 每次滚动后重新定位。
- 用业务键/行文案选择条目，不依赖当前 instance。
- 到达末尾必须有明确状态或滚动前后内容对比。
系统弹窗
权限、通知、文件选择等可能属于系统包或 SpringBoard；为其建立独立作用域和显式处理策略，不把它们当业务 App 元素。
7. 手势、输入和等待
- 点击前确认元素可见、启用且 bounds 有效。
- 输入后读取文本或等待结果状态。
- 滑动以元素/屏幕相对区域描述，不跨设备写死绝对像素。
- 页面切换等待 Activity/view/context 或业务元素变化。
- 后台切前台、横竖屏变化后重新获取元素。
- 人工验证期间可用 scrcpy/Appium Inspector 辅助观察，程序轮询真实状态并有超时。
8. 降级与留证
找不到元素先检查 context、Activity、系统弹窗、滚动位置和页面 source。确认控件树未暴露后才评估局部图像/OCR。
失败保存：
- 设备 screenshot。
- page source XML。
- serial 脱敏值、包名、Activity、context 列表。
- 屏幕分辨率、方向和系统版本。
- element map 逻辑名、定位器和匹配数量。
- App 版本、driver 版本和失败阶段。
图像方案必须限定设备矩阵和搜索区域；匹配不唯一时停止。
9. example 路由
手机 example 规格见 ../examples/mobile_rpa/README.md。在团队提供真实成功案例前，该目录只能作为实施清单和验收契约，不能作为“已跑通代码”宣传或直接复制。