# 控件 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、相似名称或第一个匹配项伪装成精确控件。