Files
pacs_win_uia/docs/XPath定位.md
T
zimoyin 9eff3ec410 悬浮条:锚定窗口只需未被完全遮挡,并跳过最小化的同名窗口
两个原因让悬浮条一直不显示:
1) 可见性规则过严——锚定窗口只要被任何外部窗口压住一角就隐藏。现在改为
   只要求“未被完全遮住”,部分遮挡不影响显示。
2) UWP 应用会留下最小化的同名框架窗口(矩形在 -32000),窗口匹配可能选中它,
   于是报“矩形过小或不在屏幕范围内”。现在优先选可见窗口;只有最小化窗口时
   明确说明原因。

实测(真实 Windows 设置窗口 + 本工具窗口压在其上 + 置顶小工具压住一角):
canShow=True,悬浮条在锚定窗口左上角显示,3 个按钮正常绘制。

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-13 15:12:05 +08:00

14 KiB
Raw Blame History

控件 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. 最小可用示例

/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 时:

  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 不能跨窗口直接使用。


六、旧格式为什么不能继续使用

以下格式已经停用:

[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)。

“匹配到多个控件”

先增加稳定祖先或属性:

//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor']

仍然多个时,再使用序号:

//*[@AutomationId='PatientPanel']//Edit[@ClassName='PatientEditor'][2]

“悬浮条保存后不显示”

点击“检测显示条件”。通常是按钮没有启用、窗口条件为空/不唯一、导入的 XPath 已失效,或目标窗口被遮挡。

“Path 看起来对,但仍找不到”

XPath 只在当前读取到的树中计算。CEF、自绘、GPU、权限隔离或未开启无障碍的界面,可能根本没有暴露目标节点。Path 无法凭空创建目标节点。


九、设计和安全边界

  • XPath 是只读定位规则,不会自动点击、输入或修改目标控件。
  • 长期配置不保存 RuntimeId、当前 Value、焦点状态等动态快照字段。
  • 姓名、身份证号、检查结果等敏感内容不应写入调试日志或 Path。
  • 截图/OCR 可能包含患者信息,应使用受控目录、保留期限和授权的本地服务。
  • 能力不足时必须报告“无法确认”,不能把 OCR、相似名称或第一个匹配项伪装成精确控件。