Files
pacs_win_uia/docs/代码导览.md
T
zimoyin 170790ff12 新增「选中行文本」取值键;点击控件框必定同步控件属性
- ControlValueKeys 新增「选中行文本」:在列表容器上直接读当前选中行的文字
  (SelectionPattern 第一个选中项 → Value → Text → Name);没有选中行时明确报错
- 控件框点选回调:无论该节点是否在当前控件树里,都更新控件属性(SelectedObject +
  ShowNodeProperties + 下方 Path 横条),并在状态栏说明是否同时选中了树节点

实测(夹具列表,启动时选中第 2 行):列表行数=3、列数=2、选中项数=1、选中行文本=项目 2
回归 29/29 通过
2026-10-13 19:28:07 +08:00

149 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 代码导览(接手必读)
> 目的:拿到这份代码的人,能在几分钟内知道**哪个功能在哪个文件**、**改动要动哪里**、**哪些地方有坑**。
>
> 项目:.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` | 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 被运行时锁定**:改完代码要编译时,先关掉正在运行的工具,或编译到别的输出目录。
---
## 四、悬浮条显示规则(当前版本)
只有**同时**满足下面条件才会显示:
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 上测过的不要写成已完成。