d7e50675f0
用户反馈两点:
1) 控件属性里也要看到内容(输入框/富文本/多行编辑器的正文)
- UiaElementInfo 新增只读展示字段「文本内容」(不序列化,选中节点时现算)
- 与取值键「文本内容」同源:Value → Text → Name
- 实测(真实 Windows 11 记事本文档节点):
文本内容="agfa\r\raaaaa",Name="文本编辑器"(通用标题)
ControlPath=/Window[1]/Pane[@ClassName='NotepadTextBox']/Document[@ClassName='RichEditD2DPT']
2) 拾取不能正确识别(实测:记事本正文拾取到 Pane[NotepadTextBox] 而不是里面的
Document[RichEditD2DPT])
- 根因:提供者的命中测试经常先返回"容器",代码直接接受了它
- FromHandleAtPoint 命中后新增 RefineHitAtPoint:在命中元素内部继续往
"包含光标的最深/最小元素"收敛(有界:节点数/深度/3 秒)
- MainForm 的"只拿到窗口再重探一次"扩展到"只拿到容器(Window/Pane/Group/Custom)
也重探一次":无障碍树按需生成的客户端第一次通常只给容器,600ms 后第二次才给到叶子
实测(真实记事本窗口内 49 个采样点):
42 × ControlType.Document / RichEditD2DPT(正文),其余为工具栏按钮/输入法宿主
修复前同一组采样中正文区域会命中 Pane
回归 27/27 通过
9.6 KiB
9.6 KiB
代码导览(接手必读)
目的:拿到这份代码的人,能在几分钟内知道哪个功能在哪个文件、改动要动哪里、哪些地方有坑。
项目:.NET Framework 4.8 + WinForms,只读的 Windows UI 自动化检查/监控工具。 解决方案:
pacs_win_uia.sln(主工程src/pacs_win_uia,测试夹具tests/uia-fixture,回归测试tests/regression)。
一、一分钟建立全局印象
Program.cs 进程入口
├─ 无参数 → 单实例:第一个进程当 owner 并开 MainForm,后面的进程把请求转发给它
└─ --read-saved/-config → 无界面读取(也可以被转发到正在运行的 GUI 实例里执行)
MainForm(UI/MainForm.cs) 三栏主界面:窗口列表 | 控件树/列表结果 | 属性 + 控件监控列表
├─ 窗口列表 NativeWindowService(Win32 枚举)
├─ 控件树 ControlTreeService → UIA / MSAA / Win32 三个来源
├─ 路径与定位 ControlPath(XPath)+ ControlLocatorService(回读)
├─ 控件监控列表 ControlMonitorEditorControl → ControlMonitorStore(JSON)
├─ 悬浮条 FloatingBarManager + FloatingToolbarForm
└─ 拾取控件 CrosshairPicker + TargetProbeService + PickerOverlayForm
数据流(最重要的一条):
窗口(PID/类名/标题) → 控件树快照(ControlTreeNode) → XPath 路径(ControlPath)
↓
监控项 JSON(只存稳定定位信息)
↓
回读:重新读树 → XPath 求值 → 唯一命中 → 读值/画框
核心原则(改代码前请先接受这四条,否则很容易改出"看起来能用但定位到错控件"的 bug):
- 找不准就说找不到。XPath 多处命中、树读取不完整、路径语法不对,一律明确报错,绝不"取第一个"。
- 动态的东西不落盘。RuntimeId、实时值、焦点状态、会变的 Name 都不写进长期配置。
- 跨进程调用可能永久卡住。任何 UIA/MSAA 调用都要有预算(
ReadBudget)、独立线程和取消,不能占 UI 线程。 - 只读。不注入、不改目标、不点击目标控件(连拾取时的鼠标左键都用低级钩子吞掉)。
二、"我要改 X,看哪个文件"
| 我想改… | 主要文件 | 备注 |
|---|---|---|
| 主界面布局/按钮/三栏比例 | UI/MainForm.cs |
布局自检 VerifyLayout() 会报错,改动后看日志 |
| 控件树怎么显示、要不要闪烁 | UI/ControlTreeReconciler.cs |
增量更新,绝不清空重建 |
| 拾取为什么选到容器 | Services/UiAutomationService.cs 的 FromHandleAtPoint |
命中后向深处收敛 |
| 控件树读取来源与顺序 | Services/ControlTreeService.cs |
Auto = UIA → MSAA → Win32 |
| UIA 快照/缓存/Pattern | Services/UiAutomationService.cs |
统一 RawView + CacheRequest |
| 列表读取(行列/单元格/降级) | Services/ListReaderService.cs |
最长的文件,见其顶部导览 |
| 取值(Name/Value/Text/选中/焦点/OCR) | Services/ControlValueReader.cs |
valueKey 的语义都在这里 |
| Path(XPath)生成与求值 | Services/ControlPath.cs |
定位核心,改这里影响全局 |
| 保存路径时的字段与校验 | Services/ControlLocatorBuilder.cs |
与回读共用匹配逻辑 |
| 回读定位(含窗口匹配) | Services/ControlLocatorService.cs |
唯一命中才返回 |
| 监控项 JSON 读写 | Services/ControlMonitorStore.cs |
加载宽松、保存严格 |
| 监控列表 UI/编辑/定位 | UI/ControlMonitorEditorControl.cs |
Path 可 F2 编辑、双击多行编辑 |
| 设置界面 | UI/SettingsForm.cs |
各页保存到 AppSettings |
| 设置的默认值与兼容 | Models/AppSettings.cs |
Normalize() 是兼容旧 JSON 的地方 |
| 悬浮条的显示条件/跟随 | Services/FloatingBarManager.cs |
见下面"悬浮条规则" |
| 悬浮条外观(自绘/透明) | UI/FloatingToolbarForm.cs |
layered window,注意 GDI 释放 |
| 遮挡/可见性判断 | Services/WindowVisibility.cs |
两个 API 用途不同,见文件头 |
| 高亮框/跟随 | Services/HighlightFollower.cs |
跟随锚点窗口的相对偏移 |
| 全部控件框绘制 | UI/NodeMapOverlayForm.cs |
只在前台窗口且未遮挡处绘制 |
| 拾取器 | Picker/CrosshairPicker.cs + UI/PickerOverlayForm.cs |
不抢焦点、吞左键 |
| 单实例/转发 | Services/SingleInstanceService.cs + Program.cs |
Mutex + 命名管道 |
| 无界面读取 | Services/HeadlessConfigReader.cs |
每条独立计时,统计口径在文件头 |
| 截图 / OCR | Services/ScreenshotService.cs、Services/OcrClient.cs |
OCR 默认关闭 |
| 命令时机与退出清理 | Services/CommandRunner.cs、Services/ProcessJob.cs |
退出时结束整棵进程树 |
| 日志 | Diagnostics/AppLog.cs |
GUI 启动会自建控制台窗口 |
三、几条容易踩的坑(都是踩过的)
- 不要在 UI 线程做 UIA/MSAA 调用:Provider 挂住时界面直接冻结。后台线程 +
ReadBudget+ 序号丢弃旧结果。 - 不要用会变的显示文本做身份:控件名可能随患者/文件/语言/计数变化。身份只用 AutomationId / ClassName / RuntimeId(运行期)/ HWND(Win32)。
- 不要清空重建控件树:300ms 刷新时清空会闪烁并丢失选择/展开,用
ControlTreeReconciler。 - 不要"取第一个匹配":不确定就报错,让人重新拾取。
- PropertyGrid 正在编辑时不要去 rebind:会打断用户输入,
MainForm里有专门判断。 - 悬浮条的"名称"不是定位条件:定位条件是进程名/窗口类/标题关键词 + 可选导入 XPath。
- 拾取到"容器"要往深处收敛:提供者的命中测试经常先给容器(实测 Windows 11 记事本正文返回
Pane[NotepadTextBox]),拾取会在命中后往下找"包含光标的更深控件",并且只拿到容器时会在 600ms 后自动重探一次。改这块看UiAutomationService.FromHandleAtPoint与MainForm.ScheduleDeeperPickRetry。 - 输入框/富文本的内容常常不在
Name里:WinForms 文本框的Name就是内容,但 WinForms 富文本、Chromium/CEF、UWP 文本框的Name可能是通用标题(例如RichEdit Control),内容只在Value/Text模式里。取内容请用跨来源键文本内容(顺序 Value → Text → Name,MSAA 侧 = accValue → accName,Win32 侧 = 窗口标题);新增/拾取控件时它已经是默认的 valueKey。 - 旧路径格式已停用:
[Uia] A[id] > B:name、Type[id]之类不再执行,只保留给人工编辑修正。 - 本工具自己的窗口不算遮挡:主界面/设置窗口压住目标不影响悬浮条显示(否则在设置页里根本测不了)。
- bin\Debug 的 exe 被运行时锁定:改完代码要编译时,先关掉正在运行的工具,或编译到别的输出目录。
四、悬浮条显示规则(当前版本)
只有同时满足下面条件才会显示:
- 悬浮条
Enabled = true,且至少有一个启用的按钮; - 窗口条件(进程名 / 窗口类 / 标题关键词)已填写的部分全部满足,且唯一匹配到一个窗口;
- 匹配时优先选可见窗口,跳过 UWP 留下的最小化同名框架窗口;
- 如果导入了监控项 XPath,该 XPath 在该窗口里唯一命中;
- 勾选了"窗口可见且未被遮挡时才显示"时:锚定窗口存在、可见、未最小化,且没有被别的程序完全遮住(部分遮挡不影响;本工具自己的窗口一律忽略)。
检测结果显示"当前不显示"时,会说明卡在哪一步,并在被外部程序遮挡时点名是哪个窗口。
四·五、配置文件位置(都在 exe 同目录)
| 文件 | 用途 |
|---|---|
control-monitors.json |
控件监控定义(界面「保存」写入) |
settings.json |
应用设置(界面、悬浮条、命令、OCR…) |
out.json |
--read-saved 的默认输出 |
旧版本的 control-monitors.json 在 %LocalAppData%\pacs_win_uia\:首次读取会自动复制到 exe 同目录(原文件保留不动);如果 exe 目录不可写,则退化为直接读旧位置,保存时会明确报错。--read-saved 在没有新文件时也会用旧位置兜底。
五、测试与验证
- 回归测试(纯内存,不需要目标程序):
想同时保留正在运行的工具实例时,加
dotnet msbuild tests\regression\RegressionTests.csproj -t:Build -p:Configuration=Debug -v:minimal tests\regression\bin\Debug\RegressionTests.exe-p:OutputPath=<临时目录>\编译到别处再运行。 - 跨进程手工夹具:
tests\run-fixture.cmd(见tests/README.md)。 - 重要:不要在本进程里用 UIA 读本工具自己的窗口,会原生崩溃。验证 UIA 逻辑必须用独立进程的夹具。
- 真机验收清单:控件树内容、拾取后树一致、列表读取行列、Path 往返(复制→按 path 定位)、
监控项保存后无界面
--read-saved命中、悬浮条按条件显示/隐藏、遮挡/最小化行为。
六、想要继续开发,建议的顺序
- 先跑一次界面 + 回归测试,确认基线正常;
- 改一个功能点,同时补一条回归用例(
tests/regression里新增Register项); - 涉及跨进程读取的改动,用独立夹具实测,不要只看编译通过;
- 改完在
TODO.md记录"已验证 / 未验证",未在真实 PACS 上测过的不要写成已完成。