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