Files
pacs_win_uia/docs/代码导览.md
T
zimoyin c1e2bd29a1 控件框面板完成:树重读后按 Path 重新绑定当前节点
- SetActiveNode/ApplyFilter 时把 _currentNode/_currentPath 换成当前快照里的新节点对象:
  实时刷新会重建节点(旧的 N 会换成新的 S),否则父子关系表以新对象为键会查不到,
  父节点/上一个/下一个在树刷新后就失效
- 代码导览补上控件框面板与空树自动开无障碍的说明

实测(独立宿主 + 跨进程读夹具树):41 个节点全部出框;面板按钮
【点击框获取path / 退出绘制 / 父节点 / 上一个 / 下一个 / 复制当前框 Path】齐备;
把列表行设为当前框后,整条祖先链(Tab→TabItem→Pane→列表→行)高亮成橙色、
其余框变淡、当前框带标签;RefreshMap / HideMap 后状态正确

回归 29/29 通过
2026-10-13 19:30:54 +08:00

11 KiB
Raw Blame History

代码导览(接手必读)

目的:拿到这份代码的人,能在几分钟内知道哪个功能在哪个文件、改动要动哪里、哪些地方有坑。

项目:.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):

  1. 找不准就说找不到。XPath 多处命中、树读取不完整、路径语法不对,一律明确报错,绝不"取第一个"。
  2. 动态的东西不落盘。RuntimeId、实时值、焦点状态、会变的 Name 都不写进长期配置。
  3. 跨进程调用可能永久卡住。任何 UIA/MSAA 调用都要有预算(ReadBudget)、独立线程和取消,不能占 UI 线程。
  4. 只读。不注入、不改目标、不点击目标控件(连拾取时的鼠标左键都用低级钩子吞掉)。

二、"我要改 X,看哪个文件"

我想改… 主要文件 备注
主界面布局/按钮/三栏比例 UI/MainForm.cs 布局自检 VerifyLayout() 会报错,改动后看日志
控件树怎么显示、要不要闪烁 UI/ControlTreeReconciler.cs 增量更新,绝不清空重建
拾取为什么选到容器 Services/UiAutomationService.cs 的 FromHandleAtPoint 命中后向深处收敛
拾取的蓝框/黄框(层级) Services/TargetProbeService.cs(FillHierarchyFrames)+ UI/PickHierarchyOverlayForm.cs 蓝=光标所在窗口,黄=向上遍历的控件链
空树自动开无障碍 Services/ControlTreeService.cs 读到空树/只有边框/渲染区域为空时自动请求开启无障碍并重读(设置里可关)
控件树读取来源与顺序 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 只在前台窗口且未遮挡处绘制;点框即选中控件树节点并刷新控件属性;右侧面板有 父节点/上一个/下一个(并高亮整条祖先链)、复制 Path、搜索与类型过滤、"仅选中及其祖先/后代"、显示标签开关;标签只画在鼠标下的那个框上
拾取器 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 被运行时锁定:改完代码要编译时,先关掉正在运行的工具,或编译到别的输出目录。

四、悬浮条显示规则(当前版本)

只有同时满足下面条件才会显示:

  1. 悬浮条 Enabled = true,且至少有一个启用的按钮;
  2. 窗口条件(进程名 / 窗口类 / 标题关键词)已填写的部分全部满足,且唯一匹配到一个窗口;
    • 匹配时优先选可见窗口,跳过 UWP 留下的最小化同名框架窗口;
  3. 如果导入了监控项 XPath,该 XPath 在该窗口里唯一命中;
  4. 勾选了"窗口可见且未被遮挡时才显示"时:锚定窗口存在、可见、未最小化,且没有被别的程序完全遮住(部分遮挡不影响;本工具自己的窗口一律忽略)。

检测结果显示"当前不显示"时,会说明卡在哪一步,并在被外部程序遮挡时点名是哪个窗口。


四·三、空树自动开无障碍(浏览器/CEF/UWP)

读到空树 / 只有窗口边框 / 里面有渲染窗口却没有子树时,ControlTreeService 会自动请求目标开启无障碍(AccessibilityActivationService)并等 900ms 重读一次:

  • 目标确实开了:节点数变多,采用新结果,状态栏说明"重读后节点 N → M";
  • 目标没暴露:如实说明"该目标没有向系统暴露无障碍树",不会假装读到了;
  • 同一窗口 60 秒内只自动激活一次;
  • 主程序里只嵌了一块浏览器区域(部分 DOM)同样适用:激活只影响那块渲染窗口,重读后它和原生控件一起出现在同一棵树里,不会改写根窗口;
  • 不想要工具动目标:设置 →「界面」里关掉"读到空树时自动请求目标开启无障碍"。

四·五、配置文件位置(都在 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 命中、悬浮条按条件显示/隐藏、遮挡/最小化行为。

六、想要继续开发,建议的顺序

  1. 先跑一次界面 + 回归测试,确认基线正常;
  2. 改一个功能点,同时补一条回归用例(tests/regression 里新增 Register 项);
  3. 涉及跨进程读取的改动,用独立夹具实测,不要只看编译通过;
  4. 改完在 TODO.md 记录"已验证 / 未验证",未在真实 PACS 上测过的不要写成已完成。