完善 XPath 定位与控件监控体验
- 增加简明到深入的 XPath 定位教程 - 保留增量控件树刷新与可编辑 Path - 完善悬浮条条件选择和诊断 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
+459
@@ -0,0 +1,459 @@
|
||||
# 控件 Path 教程:从第一次定位到稳定规则
|
||||
|
||||
> 本工具的 Path 是 **XPath 1.0 节点路径**。它只负责“在已经选定的窗口控件树里找到哪个节点”,不会点击、输入或修改目标程序。
|
||||
>
|
||||
> 最重要的原则:**宁可报告“无法唯一确定”,也不要猜一个看起来相似的控件。**
|
||||
|
||||
---
|
||||
|
||||
## 一、先用 3 分钟完成第一次定位
|
||||
|
||||
### 1. 取得 Path
|
||||
|
||||
1. 在主界面的“窗口列表”选中目标窗口。
|
||||
2. 等待“控件树”读取完成。
|
||||
3. 在控件树中选中目标控件。
|
||||
4. 在右侧“控件属性”中找到 `ControlPath`。
|
||||
5. 复制这个 XPath,或点击“添加当前控件”加入“控件监控列表”。
|
||||
|
||||
拾取控件也会从**同一个顶层窗口控件树**生成 Path,所以“手动选树节点”和“鼠标拾取”产生的 Path 应当使用同一套规则。
|
||||
|
||||
### 2. 测试 Path
|
||||
|
||||
在控件监控列表中可以:
|
||||
|
||||
- 选中 `控件Path` 单元格后按 `F2` 直接编辑;
|
||||
- 双击 Path 打开多行 XPath 编辑器;
|
||||
- 点击“测试定位”检查当前窗口是否**唯一命中**;
|
||||
- 点击“定位到”在树中展开并高亮目标;
|
||||
- 最后点击监控列表的“保存”才会写入 JSON。
|
||||
|
||||
测试结果有三种:
|
||||
|
||||
| 结果 | 含义 |
|
||||
|---|---|
|
||||
| 唯一命中 | 可以保存并用于监控 |
|
||||
| 0 个命中 | 当前页面没有这个节点,或条件写错 |
|
||||
| 多个命中 | 条件太宽,必须继续增加约束 |
|
||||
|
||||
### 3. 最小可用示例
|
||||
|
||||
```xpath
|
||||
/Window[1]
|
||||
```
|
||||
|
||||
表示当前树的顶层窗口。
|
||||
|
||||
```xpath
|
||||
/Window[1]//Button[@AutomationId='saveButton']
|
||||
```
|
||||
|
||||
表示窗口内任意层级、`AutomationId` 为 `saveButton` 的按钮。
|
||||
|
||||
```xpath
|
||||
/Window[1]//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor']
|
||||
```
|
||||
|
||||
表示先找到稳定的患者面板,再在面板内部找编辑框。
|
||||
|
||||
---
|
||||
|
||||
## 二、你需要先理解的 4 个概念
|
||||
|
||||
### 1. 窗口条件和控件 Path 是两层定位
|
||||
|
||||
程序先通过窗口条件找到**哪个顶层窗口**,再用 XPath 找窗口里面的**哪个控件**。
|
||||
|
||||
窗口条件通常包括:
|
||||
|
||||
- 进程名;
|
||||
- 窗口类名;
|
||||
- 标题关键词。
|
||||
|
||||
已经填写的窗口条件会同时满足,并且必须唯一匹配。窗口标题只用于找窗口,不等同于控件 Path 中的 `@Name`。
|
||||
|
||||
因此下面两件事是不同的:
|
||||
|
||||
```text
|
||||
窗口条件:进程=MyPacs;窗口类=PacsMainWindow
|
||||
控件 Path:/Window[1]//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor']
|
||||
```
|
||||
|
||||
窗口条件解决“去哪一棵树”;XPath 解决“树里的哪一个节点”。
|
||||
|
||||
### 2. 控件类型是节点名称
|
||||
|
||||
常见节点名称包括:
|
||||
|
||||
```text
|
||||
Window Pane Group Button
|
||||
Edit Text List ListItem
|
||||
Tree Tab TabItem CheckBox
|
||||
ComboBox ScrollBar Custom
|
||||
```
|
||||
|
||||
XPath 中的 `Edit`、`Button` 等来自 UIA 控件类型。不同来源也会映射为树节点,例如 MSAA/Win32 节点可能显示为 `Accessible` 或 `Window`。
|
||||
|
||||
### 3. 属性是节点的特征
|
||||
|
||||
常用属性:
|
||||
|
||||
| 属性 | 适合用途 | 稳定性提醒 |
|
||||
|---|---|---|
|
||||
| `@AutomationId` | 程序给控件的逻辑 ID | 通常最适合长期定位,但目标程序也可能生成动态 ID |
|
||||
| `@ClassName` | 控件/窗口类名 | 比显示文字稳定,但框架升级可能改变 |
|
||||
| `@ControlType` | 精确区分控件类型 | 一般与节点名称对应 |
|
||||
| `@Name` | 按钮文字、标签文字、列表项文字 | 最容易随患者、文件、语言、状态变化 |
|
||||
| `@Source` | 区分 UIA、MSAA、Win32 | 多来源树不能混为一棵树 |
|
||||
|
||||
例如:
|
||||
|
||||
```xpath
|
||||
//Button[@AutomationId='saveButton']
|
||||
//Edit[@ClassName='PatientEditor']
|
||||
//*[@ControlType='ControlType.ListItem']
|
||||
//*[@Source='Win32']
|
||||
```
|
||||
|
||||
### 4. 唯一命中比“写得像”更重要
|
||||
|
||||
这条路径可能看起来合理:
|
||||
|
||||
```xpath
|
||||
//Button
|
||||
```
|
||||
|
||||
但一个页面通常有很多按钮,所以它不能用于监控定位。
|
||||
|
||||
可以搜索时使用宽路径,但保存或定位必须收窄到唯一节点:
|
||||
|
||||
```xpath
|
||||
//Button[@ClassName='ActionButton' and contains(@Name,'保存')]
|
||||
```
|
||||
|
||||
如果仍然有两个结果,再增加稳定祖先、AutomationId 或同级序号。
|
||||
|
||||
---
|
||||
|
||||
## 三、XPath 语法速查
|
||||
|
||||
### 1. `/`:直接子节点
|
||||
|
||||
```xpath
|
||||
/Window[1]/Pane/Button
|
||||
```
|
||||
|
||||
只查直接下一层。中间缺一层就匹配不到。
|
||||
|
||||
### 2. `//`:任意后代节点
|
||||
|
||||
```xpath
|
||||
/Window[1]//Button
|
||||
```
|
||||
|
||||
查找窗口下面任意深度的按钮。页面有动态布局时,`//` 通常比写死全部中间 Pane 更耐用,但也更容易产生多个结果,需要加条件。
|
||||
|
||||
### 3. `*`:任意控件类型
|
||||
|
||||
```xpath
|
||||
/Window[1]//*[@AutomationId='PatientPanel']
|
||||
```
|
||||
|
||||
适合先用稳定属性找锚点,不确定控件类型时也很有用。
|
||||
|
||||
### 4. 属性条件 `[@属性='值']`
|
||||
|
||||
```xpath
|
||||
//Edit[@AutomationId='PatientId']
|
||||
//Button[@ClassName='ActionButton']
|
||||
```
|
||||
|
||||
### 5. 多条件 `and` / `or`
|
||||
|
||||
```xpath
|
||||
//Edit[@ClassName='PatientEditor' and @AutomationId='PatientId']
|
||||
//Button[@AutomationId='save' or @AutomationId='submit']
|
||||
```
|
||||
|
||||
长期监控优先使用 `and`,因为它能减少误匹配。
|
||||
|
||||
### 6. `contains()`:部分匹配
|
||||
|
||||
```xpath
|
||||
//Button[contains(@Name,'保存')]
|
||||
//Text[contains(@Name,'患者编号')]
|
||||
```
|
||||
|
||||
适合名称有固定部分、但后面会变化的情况,例如“保存(3)”。
|
||||
|
||||
注意:`contains()` 可能匹配多个节点,必须测试唯一性。
|
||||
|
||||
### 7. `starts-with()`:固定前缀
|
||||
|
||||
```xpath
|
||||
//Text[starts-with(@Name,'患者编号')]
|
||||
```
|
||||
|
||||
如果控件名称是“患者编号:张三”,而“患者编号”稳定,可以使用它。
|
||||
|
||||
### 8. 序号 `[n]`
|
||||
|
||||
序号从 **1** 开始:
|
||||
|
||||
```xpath
|
||||
//Button[1]
|
||||
//Button[2]
|
||||
(//Button[@AutomationId='same-id'])[2]
|
||||
```
|
||||
|
||||
序号表示当前 XPath 结果中的位置,不是永久 ID。页面插入一个同类型控件后,序号可能改变,所以只能作为最后的消歧手段。
|
||||
|
||||
### 9. 组合条件
|
||||
|
||||
```xpath
|
||||
/Window[1]//*[@AutomationId='PatientPanel']//Group[
|
||||
.//Text[@AutomationId='PatientIdLabel']
|
||||
]//Edit[@ClassName='PatientEditor']
|
||||
```
|
||||
|
||||
这是更稳定的思路:先找业务面板,再找面板内由稳定标签限定的编辑框。
|
||||
|
||||
### 10. 选择节点集,不要返回值
|
||||
|
||||
Path 必须返回控件节点集合。下面这些不是可定位 Path:
|
||||
|
||||
```xpath
|
||||
count(//Button)
|
||||
string(//Text/@Name)
|
||||
/Window/@Name
|
||||
text()
|
||||
```
|
||||
|
||||
它们返回数字、字符串、属性或文本,而不是控件节点。
|
||||
|
||||
---
|
||||
|
||||
## 四、Name 会变化时,怎样尽量精准定位
|
||||
|
||||
这是最常见也最容易误定位的场景。
|
||||
|
||||
### 推荐优先级
|
||||
|
||||
#### 第一优先:AutomationId
|
||||
|
||||
```xpath
|
||||
/Window[1]//*[@AutomationId='PatientPanel']//Edit[@AutomationId='PatientId']
|
||||
```
|
||||
|
||||
如果目标程序提供稳定 ID,不要额外把动态 Name 写进条件。
|
||||
|
||||
#### 第二优先:稳定祖先 + ClassName + 类型
|
||||
|
||||
```xpath
|
||||
/Window[1]//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor']
|
||||
```
|
||||
|
||||
中间布局层可以增加、减少或更换名称,通常不会影响这条路径。
|
||||
|
||||
#### 第三优先:稳定辅助节点
|
||||
|
||||
```xpath
|
||||
/Window[1]//Group[
|
||||
.//Text[@AutomationId='PatientIdLabel']
|
||||
]//Edit[@ClassName='PatientEditor']
|
||||
```
|
||||
|
||||
辅助节点必须和目标有明确结构关系。不要只在整个窗口中搜索一个相似文字,然后猜最近的控件。
|
||||
|
||||
#### 第四优先:名称的稳定部分
|
||||
|
||||
```xpath
|
||||
//Text[starts-with(@Name,'患者编号')]
|
||||
//Button[contains(@Name,'保存') and @ClassName='ActionButton']
|
||||
```
|
||||
|
||||
只有名称的一部分稳定时才这样写,并且一定点击“测试定位”确认唯一。
|
||||
|
||||
#### 第五优先:结构序号
|
||||
|
||||
```xpath
|
||||
//*[@AutomationId='PatientPanel']//Edit[2]
|
||||
```
|
||||
|
||||
这是最后手段。结构变化、权限变化、页面状态变化都可能让 `[2]` 指向另一个控件。
|
||||
|
||||
### 自动生成路径的策略
|
||||
|
||||
当前工具自动生成 Path 时:
|
||||
|
||||
1. 根窗口固定为 `/Window[1]`,不依赖窗口标题;
|
||||
2. 子节点优先使用 AutomationId;
|
||||
3. 没有 AutomationId 时使用 ClassName 和控件类型;
|
||||
4. 没有稳定属性时使用类型和结构序号;
|
||||
5. 不自动把 Name 写成长期必经条件。
|
||||
|
||||
这能避免患者姓名、文件名、数量、语言变化直接让路径失效。
|
||||
|
||||
### 无法保证的情况
|
||||
|
||||
如果目标程序同时满足以下条件:
|
||||
|
||||
- 没有稳定 AutomationId;
|
||||
- ClassName 也会变化;
|
||||
- 中间结构会动态重排;
|
||||
- 没有稳定辅助标签或业务锚点;
|
||||
- 控件本身是自绘且不暴露 UIA;
|
||||
|
||||
那么 UIA XPath 没有足够信息证明“这就是同一个业务控件”。此时不应继续堆叠猜测条件,应考虑:
|
||||
|
||||
- 让目标程序提供稳定无障碍 ID;
|
||||
- 使用官方插件/API;
|
||||
- 切换 MSAA/Win32 来源;
|
||||
- 对明确授权的场景使用截图/OCR,并标记为降级结果;
|
||||
- 页面变化后要求人工重新确认。
|
||||
|
||||
RuntimeId 和 HWND 适合当前运行中的重新绑定,不适合直接作为跨重启、跨版本的长期配置身份。
|
||||
|
||||
---
|
||||
|
||||
## 五、Path 的编辑、测试和保存
|
||||
|
||||
### 直接编辑
|
||||
|
||||
在“控件监控列表”中:
|
||||
|
||||
1. 选中 `控件Path` 单元格;
|
||||
2. 按 `F2` 或直接输入;
|
||||
3. 输入期间不会自动定位,避免半截 XPath 造成界面跳动;
|
||||
4. 按 Enter/离开单元格提交;
|
||||
5. 点击“测试定位”或“定位到”;
|
||||
6. 点击列表的“保存”写入 JSON。
|
||||
|
||||
### 多行编辑器
|
||||
|
||||
双击 Path 会打开“编辑控件 XPath”窗口:
|
||||
|
||||
- 上方显示 XPath 快速说明;
|
||||
- 中间可以编辑长路径;
|
||||
- “测试定位”在后台执行,不阻塞窗口;
|
||||
- 0 个或多个结果会显示错误;
|
||||
- 非法语法不能保存;
|
||||
- “取消”不会修改原 Path;
|
||||
- 右键菜单仍可复制 Path。
|
||||
|
||||
### 按 path 定位
|
||||
|
||||
打开“杂项 → 按 path 定位”:
|
||||
|
||||
1. 先选中目标窗口并读取控件树;
|
||||
2. 粘贴完整 XPath;
|
||||
3. 点击“定位”;
|
||||
4. 唯一命中时,工具会在树中选择节点并尝试画框。
|
||||
|
||||
当前窗口树必须是你复制 Path 时对应的窗口树。Path 不能跨窗口直接使用。
|
||||
|
||||
---
|
||||
|
||||
## 六、旧格式为什么不能继续使用
|
||||
|
||||
以下格式已经停用:
|
||||
|
||||
```text
|
||||
[Uia] Window:设置 > Custom[PermanentNavigationView] > Button:个性化
|
||||
Button[saveButton]
|
||||
i3/o1
|
||||
[Win32] ClassName 0x1234
|
||||
```
|
||||
|
||||
原因是这些格式存在多个问题:
|
||||
|
||||
- 显示文本和真实属性混在一起;
|
||||
- `:`、`>`、`[` 等字符无法可靠转义;
|
||||
- 同名节点的序号语义容易不一致;
|
||||
- 不同来源的路径不能放在同一套解析器里猜测;
|
||||
- 失败时容易静默回退到另一个控件。
|
||||
|
||||
旧配置仍可读取并显示,方便手工修正;但旧 Path 不会执行,保存前必须改成 XPath。保存失败时原文件保持不变,不会自动清空或改写旧配置。
|
||||
|
||||
---
|
||||
|
||||
## 七、悬浮条中使用 XPath
|
||||
|
||||
在“设置 → 悬浮按钮”中:
|
||||
|
||||
1. 选择或新建悬浮条;
|
||||
2. 配置进程名、窗口类或标题关键词;
|
||||
3. 点击“导入监控项 path”;
|
||||
4. 选择要导入的监控项;
|
||||
5. 点击“检测显示条件”;
|
||||
6. 确认悬浮条启用,并至少有一个启用按钮;
|
||||
7. 点击设置窗口“保存”。
|
||||
|
||||
导入内容是定位条件的副本。之后修改监控列表中的 XPath,不会自动改变已经导入的悬浮条;请重新导入。
|
||||
|
||||
下拉框显示的是“窗口标题 / 进程名 / PID / 窗口类”等人类可读信息,但保存的是实际条件值。悬浮条名称只用于显示,不是窗口定位条件。
|
||||
|
||||
### 不显示时的排查顺序
|
||||
|
||||
点击“检测显示条件”,按提示处理:
|
||||
|
||||
1. 悬浮条是否启用;
|
||||
2. 是否有至少一个启用按钮;
|
||||
3. 是否填写了窗口条件;
|
||||
4. 已填写的进程、类名、标题是否同时匹配;
|
||||
5. 是否匹配到多个窗口;
|
||||
6. 导入 XPath 是否仍然唯一命中;
|
||||
7. 窗口是否最小化、隐藏或被遮挡;
|
||||
8. 设置窗口自身是否挡住了目标。
|
||||
|
||||
---
|
||||
|
||||
## 八、常见错误速查
|
||||
|
||||
### “旧路径格式已停用”
|
||||
|
||||
请回到控件树复制新的 `ControlPath`,或者手工改成 XPath。不要给旧格式加一个 `/` 试图伪装成 XPath。
|
||||
|
||||
### “路径匹配到 0 个控件”
|
||||
|
||||
检查:
|
||||
|
||||
1. 是否选中了正确的顶层窗口;
|
||||
2. 控件树是否读取完整;
|
||||
3. 控件类型是否正确;
|
||||
4. AutomationId/ClassName 是否发生变化;
|
||||
5. 是否把临时患者姓名或文件名写进了 `@Name`;
|
||||
6. 页面是否已切换或控件已重建;
|
||||
7. 是否选错了来源(UIA、MSAA、Win32)。
|
||||
|
||||
### “匹配到多个控件”
|
||||
|
||||
先增加稳定祖先或属性:
|
||||
|
||||
```xpath
|
||||
//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor']
|
||||
```
|
||||
|
||||
仍然多个时,再使用序号:
|
||||
|
||||
```xpath
|
||||
//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor'][2]
|
||||
```
|
||||
|
||||
### “悬浮条保存后不显示”
|
||||
|
||||
点击“检测显示条件”。通常是按钮没有启用、窗口条件为空/不唯一、导入的 XPath 已失效,或目标窗口被遮挡。
|
||||
|
||||
### “Path 看起来对,但仍找不到”
|
||||
|
||||
XPath 只在当前读取到的树中计算。CEF、自绘、GPU、权限隔离或未开启无障碍的界面,可能根本没有暴露目标节点。Path 无法凭空创建目标节点。
|
||||
|
||||
---
|
||||
|
||||
## 九、设计和安全边界
|
||||
|
||||
- XPath 是只读定位规则,不会自动点击、输入或修改目标控件。
|
||||
- 长期配置不保存 RuntimeId、当前 Value、焦点状态等动态快照字段。
|
||||
- 姓名、身份证号、检查结果等敏感内容不应写入调试日志或 Path。
|
||||
- 截图/OCR 可能包含患者信息,应使用受控目录、保留期限和授权的本地服务。
|
||||
- 能力不足时必须报告“无法确认”,不能把 OCR、相似名称或第一个匹配项伪装成精确控件。
|
||||
Reference in New Issue
Block a user