Files
pacs_win_uia/docs/XPath定位.md
T
zimoyin 170790ff12 新增「选中行文本」取值键;点击控件框必定同步控件属性
- ControlValueKeys 新增「选中行文本」:在列表容器上直接读当前选中行的文字
  (SelectionPattern 第一个选中项 → Value → Text → Name);没有选中行时明确报错
- 控件框点选回调:无论该节点是否在当前控件树里,都更新控件属性(SelectedObject +
  ShowNodeProperties + 下方 Path 横条),并在状态栏说明是否同时选中了树节点

实测(夹具列表,启动时选中第 2 行):列表行数=3、列数=2、选中项数=1、选中行文本=项目 2
回归 29/29 通过
2026-10-13 19:28:07 +08:00

498 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 控件 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,'患者编号')]
```
如果控件名称是“患者编号:张三”,而“患者编号”稳定,可以使用它。
### 7b. 状态属性:选"当前选中行 / 焦点行"
节点上除了名称类属性,还有四个状态属性,值是 `'true'` / `'false'`(状态未知时不写这个属性):
| 属性 | 含义 | 来源 |
|---|---|---|
| `@IsSelected` | 是否被选中 | 行/项自己的 SelectionItemPattern,或从容器的 SelectionPattern 反推 |
| `@IsFocused` | 是否是当前焦点元素 | UIA HasKeyboardFocus |
| `@IsOffscreen` | 是否在屏幕外(被滚动出视图/折叠) | UIA IsOffscreen |
| `@IsEnabled` | 是否可用(未禁用) | UIA IsEnabled |
因此"拿当前选中行 / 焦点行"不用再写序号:
```xpath
/Window[1]//DataGrid[@AutomationId='FixtureListView']/DataItem[@IsSelected='true']
/Window[1]//DataGrid[@AutomationId='FixtureListView']/DataItem[@IsFocused='true']
```
配合取值键 `文本内容`,就能直接读到那一行的文字。注意:`@IsFocused` 取决于焦点此刻在哪个窗口;`@IsSelected` 对一次性列出选中集合的提供者(如 WinForms 列表)由容器反推得来。
### 7c. 列表信息:不用整表读取也能盯住表格
容器控件(List / DataGrid / Table / Tree)上多出三个取值键,适合放进控件监控:
| 取值键 | 含义 |
|---|---|
| `列表行数` | 行数(GridPattern 优先,其次 TablePattern) |
| `列表列数` | 列数 |
| `列表选中项数` | 当前选中项数 |
| `选中行文本` | 当前选中那一行的文字(在列表容器上直接读,不用先选行) |
需要完整行列数据时仍然用「读取选中控件列表」。
### 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 的编辑、测试和保存
### 直接编辑
在“控件监控列表”中,点击任意一行(或“定位到控件”按钮)都会:先在屏幕上高亮该控件,**同时在控件树里展开祖先并选中该节点**,控件树下方的 Path 横条也会同步显示它的 XPath。即使当前画不出高亮框(目标最小化、被别的程序遮住、或控件没有矩形),控件树的联动照样发生。
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 / 窗口类”等人类可读信息,但保存的是实际条件值。悬浮条名称只用于显示,不是窗口定位条件。
### 不显示时的排查顺序
点击“检测显示条件”,按提示处理:
> - 本工具自己的窗口(主界面、设置窗口)**永远不算遮挡**:在设置窗口里配置时,悬浮条照样按条件显示。
> - 别的程序**只是压住锚定窗口的一部分**(例如一个置顶小工具压住一个角)也不影响显示。
> - 只有锚定窗口**被别的程序完全遮住**、或者它本身最小化/隐藏了,悬浮条才不显示,并在检测结果里点名是哪个窗口挡住的。
> - 如果匹配到的窗口是**最小化**的(UWP 应用常留下一个最小化的同名框架窗口),检测会明确说明,不会再把它当成正常锚点。
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、相似名称或第一个匹配项伪装成精确控件。