0e4bccf3f5
- 第 8 层:settings.json 各节字段、control-monitors.json 逐字段(含旧字段与 不落盘字段的说明)、out.json 结果结构 - 第 9 层:valueKey 全表(跨来源键 + UIA/MSAA/Win32 各自键),并说明键可手填、 填错会明确报错 - 第 10 层:五个常见任务的照做步骤(加控件 / 盯表格行 / 悬浮条条件 / 无界面读取含退出码流程图 / 读不到的排查顺序) - 时序图、状态图、类图移到文末「附:三张补充图」,0~10 层保持连续好读 - 共 13 张 Mermaid 图
487 lines
22 KiB
Markdown
487 lines
22 KiB
Markdown
# 最小系统(一层层看懂这个工具)
|
||
|
||
> 读法:从**第 0 层**看起,每加一层只多一个概念,配一张图。看完 0~4 层,这个工具你就懂八成了;
|
||
> 5~8 层是界面与周边功能;最后几节是排错对照表和"读代码的顺序"。
|
||
>
|
||
> 图都用 **Mermaid**(文字转图)语法写:` ```mermaid ` 代码块里的文字就是图。
|
||
>
|
||
> 怎么看到图(任选一种):
|
||
> - VS Code / Rider:装 Markdown 预览的 Mermaid 插件(VS Code 用 "Markdown Preview Mermaid Support"),预览即可;
|
||
> - Typora / Obsidian:直接预览;
|
||
> - 不想装东西:把某个 ```mermaid 代码块的内容贴到 <https://mermaid.live> 左侧,右侧立刻出图;
|
||
> - 推送到 GitLab/GitHub 后,网页上会自动渲染。
|
||
>
|
||
> 想改图:直接改代码块里的文字,不用画图工具。
|
||
|
||
---
|
||
|
||
## 第 0 层:最小系统 = 一条四步链路
|
||
|
||
整个工具,剥掉所有界面和周边功能,只剩四步:
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["目标程序<br/>(PACS 客户端 / 记事本 / 浏览器)"] -->|"① 找窗口"| B["NativeWindowService<br/>按 进程名 / 窗口类 / 标题 匹配"]
|
||
B -->|"② 读控件树"| C["ControlTreeService<br/>UIA → MSAA → Win32"]
|
||
C -->|"③ 算路径"| D["ControlPath<br/>XPath 唯一命中"]
|
||
D -->|"④ 取值"| E["ControlValueReader<br/>Value → Text → Name"]
|
||
```
|
||
|
||
- **第 0 层的关键词**:窗口 → 控件树 → 路径 → 值。
|
||
- 后面所有的功能(拾取、监控列表、悬浮条、控件框、无界面读取)都只是这四步的不同包装。
|
||
- 所以**遇到问题先问自己:卡在这四步里的哪一步?**(对应文件见文末对照表)
|
||
|
||
---
|
||
|
||
## 第 1 层:窗口是怎么找到的
|
||
|
||
目标程序可能开了好几个窗口,DLL 里的控件又没有独立窗口。所以第一步先锁定"哪一棵树"。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["EnumWindows<br/>枚举所有可见顶层窗口"] --> B["抓取快照<br/>HWND / PID / 进程名 / 类名 / 标题 / 矩形"]
|
||
B --> C{"按条件过滤<br/>(保存监控时记下的线索)"}
|
||
C -->|"进程名 + 窗口类 + 标题<br/>全中"| D["✅ 最精确"]
|
||
C -->|"只中进程名+窗口类"| E["⚠ 程序可能升级过<br/>(窗口类会变)"]
|
||
C -->|"只中进程名+标题"| F["⚠ 标题随内容变过"]
|
||
C -->|"只有进程名"| G["⚠ 较宽,需要人工核对"]
|
||
C -->|"多个候选"| H["❌ 报错要求补条件<br/>绝不随便取第一个"]
|
||
```
|
||
|
||
要点:
|
||
|
||
- 匹配是**分级降级**的:越靠上越可信;用了下面几级,工具会在状态栏明说"需要人工核对"。
|
||
- **标题只用来找窗口**,不是控件路径的一部分(标题常含文件名/患者姓名,会变)。
|
||
- 窗口快照里还会存:是否可见、是否最小化、样式(`GWL_STYLE`/`GWL_EXSTYLE`)——排查"为什么命中的是这一层"很有用。
|
||
|
||
对应代码:`Services/NativeWindowService.cs`、`Services/WindowMatcher.cs`、`Services/ControlLocatorService.cs`(匹配窗口那部分)。
|
||
|
||
---
|
||
|
||
## 第 2 层:控件树从哪来(三个来源)
|
||
|
||
Windows 上的"控件信息"有三套互不相通的体系。工具同时用,按顺序取第一个**有内容**的:
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
R["ControlTreeService.Read(窗口HWND)"] --> U{"UIA 读得到内容吗?"}
|
||
U -->|"只有根节点/只有标题栏"| ACT["自动请求目标开启无障碍<br/>(Chromium/CEF/UWP 常见)"]
|
||
ACT --> U2{"重读后有内容吗?"}
|
||
U2 -->|"有"| OK["用 UIA 树"]
|
||
U2 -->|"还是没有"| M{"MSAA 读得到内容吗?"}
|
||
U -->|"有"| OK
|
||
M -->|"有"| OKM["用 MSAA 树"]
|
||
M -->|"没有"| W{"Win32 有多少子窗口?"}
|
||
W -->|"有"| OKW["用 Win32 树"]
|
||
W -->|"没有"| EMPTY["如实报告:该目标没有暴露内部控件"]
|
||
```
|
||
|
||
三个来源各自能看到什么(**不要混用**):
|
||
|
||
| | UIA | MSAA | Win32 |
|
||
|---|---|---|---|
|
||
| 能看到 | 控件类型、名称、AutomationId、模式(Value/Text/Grid…) | 传统控件、列表行(保真度低) | **每个真实子窗口**(HWND/类名/矩形) |
|
||
| 看不到 | 未开无障碍的自绘界面 | 部分现代控件细节 | 自绘区域内的"控件" |
|
||
| 代价 | 跨进程调用,可能卡住 | 同左 | 本机枚举,最快最稳 |
|
||
|
||
要点:
|
||
|
||
- 树一律按 **RawView** 读(包含不可见/非"控件"元素),因为那才是你眼睛看到的那棵树。
|
||
- 读树用 `CacheRequest` 一次性批量取属性,否则每个节点都是一次跨进程调用,大窗口会慢到几秒。
|
||
- 读完后会给每个节点算好 `CanonicalPath`(见第 3 层),并**由容器反推每行的选中状态**(WinForms 列表的行自身不报选中)。
|
||
|
||
对应代码:`Services/ControlTreeService.cs`、`Services/UiAutomationService.cs`、`Services/MsaaTreeReader.cs`、`Services/Win32TreeReader.cs`、`Services/ReadBudget.cs`。
|
||
|
||
---
|
||
|
||
## 第 3 层:路径(XPath)——定位的核心
|
||
|
||
路径不是"一串名字",而是**在快照上跑 XPath 1.0**:
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph 生成
|
||
A["控件树节点"] --> B["把树写成 XML<br/>节点名=控件类型,属性=Name/AutomationId/ClassName/状态"]
|
||
B --> C["算 CanonicalPath<br/>AutomationId → ClassName+类型 → 类型序号"]
|
||
end
|
||
subgraph 回读
|
||
D["保存的 XPath"] --> E["重新读树 → 同一套 XML"]
|
||
E --> F["求值"]
|
||
F -->|"命中 1 个"| G["✅ 定位成功"]
|
||
F -->|"0 个 / 多个"| H["❌ 明确报错<br/>不猜、不取第一个"]
|
||
end
|
||
```
|
||
|
||
可以用在路径里的东西:
|
||
|
||
| 写法 | 含义 |
|
||
|---|---|
|
||
| `/Window[1]/Tab[@AutomationId='FixtureTabs']/…` | 一级级往下(绝对路径,含窗口根) |
|
||
| `//DataItem[...]` | 任意深度找(层级会变时更耐用,但要确认唯一) |
|
||
| `@Name` `@AutomationId` `@ClassName` `@ControlType` `@Source` | 属性条件 |
|
||
| `@IsSelected` `@IsFocused` `@IsOffscreen` `@IsEnabled` | 状态条件(值 `'true'`/`'false'`) |
|
||
| `contains(@Name,'保存')`、`and`、`or` | 部分匹配与组合 |
|
||
| `DataItem[2]` | 同级第几个(**最后手段**,结构一变就指错) |
|
||
|
||
**Name 会变怎么办**:优先 `AutomationId` → 稳定祖先 + `ClassName` → 稳定辅助节点 → 名称的稳定片段 → 序号。
|
||
详细原则见 `docs/XPath定位.md`。
|
||
|
||
对应代码:`Services/ControlPath.cs`(求值/生成)、`Services/ControlLocatorBuilder.cs`(怎么算路径)、`Services/ControlLocatorService.cs`(怎么回读)。
|
||
|
||
---
|
||
|
||
## 第 4 层:取值(valueKey)
|
||
|
||
定位到节点后,"读什么"由 valueKey 决定。最容易踩的坑是 **Name 不是内容**:
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["valueKey = 文本内容"] --> B{"ValuePattern 有值吗?"}
|
||
B -->|"有"| Z["✅ 用它"]
|
||
B -->|"没有"| C{"TextPattern 有值吗?"}
|
||
C -->|"有"| Z
|
||
C -->|"没有"| D{"Name 非空吗?"}
|
||
D -->|"有"| Z
|
||
D -->|"都没有"| E["❌ 报错并列出各自原因"]
|
||
```
|
||
|
||
- 记事本文档:`Name = 文本编辑器`(标题),内容在 `Value`/`Text` 里;
|
||
- WinForms 文本框:`Name` 就是内容;
|
||
- 所以**新增控件默认用 `文本内容`**,两头都吃得下。
|
||
|
||
其它常用键:`Value` `Text` `选中状态` `焦点状态` `选中行文本` `列表行数` `列表列数` `列表选中项数` `OCR文本`。
|
||
|
||
对应代码:`Services/ControlValueReader.cs`、`Models/ControlLocator.cs`(键清单)。
|
||
|
||
---
|
||
|
||
## 第 5 层:把上面四步变成"能长期用"
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["加控件<br/>(拾取或选树节点)"] --> B["存成监控项 JSON<br/>窗口条件 + XPath + valueKey"]
|
||
B --> C["界面点一行<br/>→ 定位 + 画框 + 选中树节点"]
|
||
B --> D["无界面 --read-saved<br/>→ 逐个定位取值 → out.json"]
|
||
B --> E["悬浮条导入 path<br/>→ 该控件出现时才显示按钮"]
|
||
```
|
||
|
||
- 监控 JSON **只存稳定信息**:窗口条件、XPath、valueKey、超时;RuntimeId、当前值、焦点这类"此刻状态"不落盘。
|
||
- 无界面读取每条独立计时,结果分四类计数:命中 / 未定位 / 取不到值 / 已停用跳过。
|
||
- 配置文件都在 **exe 同目录**(`control-monitors.json`、`settings.json`、`out.json`),整包拷走即可。
|
||
|
||
对应代码:`Services/ControlMonitorStore.cs`、`Services/HeadlessConfigReader.cs`、`Services/FloatingBarManager.cs`。
|
||
|
||
---
|
||
|
||
## 第 6 层:界面(三栏 + 两个浮层)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph 主界面
|
||
L["左:窗口列表<br/>搜索/前台高亮"]
|
||
M["中:控件树 + 列表结果<br/>搜索 + 选中 Path 横条"]
|
||
R["右:控件属性 + 控件监控列表"]
|
||
end
|
||
L -->|"选中窗口"| M
|
||
M -->|"选中节点"| R
|
||
R -->|"点一行"| M
|
||
```
|
||
|
||
两个浮层(都不抢焦点、点击穿透):
|
||
|
||
| 浮层 | 什么时候出现 | 有什么 |
|
||
|---|---|---|
|
||
| 拾取层级框 | 拾取悬停预览 | **蓝框=光标所在窗口**,**黄框=向上遍历的控件链** |
|
||
| 控件框面板 | 杂项 →「绘制所有控件框」 | 每个控件一个框;右侧面板:父节点/上一个/下一个(高亮整条祖先链)、复制 Path、搜索、类型过滤、大小位置、悬停标签 |
|
||
|
||
对应代码:`UI/MainForm.cs`、`UI/ControlMonitorEditorControl.cs`、`Picker/CrosshairPicker.cs`、`UI/PickHierarchyOverlayForm.cs`、`UI/NodeMapOverlayForm.cs`。
|
||
|
||
---
|
||
|
||
## 第 7 层:周边(按需了解)
|
||
|
||
| 功能 | 一句话 | 文件 |
|
||
|---|---|---|
|
||
| 单实例 | 第二个进程不干活,把请求转给已运行的实例(Mutex + 命名管道) | `Services/SingleInstanceService.cs`、`Program.cs` |
|
||
| 命令时机 | 启动/退出/定时/单次执行命令;退出时连命令拉起的子进程一起结束 | `Services/CommandRunner.cs`、`Services/ProcessJob.cs` |
|
||
| 截图 | PrintWindow → BitBlt → 屏幕拷贝,并校验不是全黑/全白 | `Services/ScreenshotService.cs` |
|
||
| OCR | 本地服务,默认关闭;只读值失败时可降级为"截图识别",会标注来源 | `Services/OcrClient.cs` |
|
||
| 列表读取 | Grid/Table 模式 → 遍历降级;读不到就如实报告,不伪造 | `Services/ListReaderService.cs` |
|
||
|
||
---
|
||
|
||
## 第 8 层:两个配置文件里到底有什么
|
||
|
||
两个文件都在 **exe 同目录**,纯文本 JSON,可以手改、可随包分发。
|
||
|
||
### settings.json(应用设置)
|
||
|
||
| 节 | 关键字段 | 作用 |
|
||
|---|---|---|
|
||
| `Ui` | `AutoReadTreeOnSelect` | 窗口列表选中一行就自动读树 |
|
||
| | `AutoActivateAccessibility` | 读到空树/只有边框时自动请求目标开启无障碍(默认 true) |
|
||
| | `TreeMaxDepth` / `TreeMaxNodes` / `TreeTimeoutSeconds` | 控件树的深度/节点/超时上限 |
|
||
| | `TreeRefreshIntervalMs` | 实时刷新间隔(默认 300ms) |
|
||
| | `HighlightForegroundWindow` | 窗口列表里给前台窗口上色 |
|
||
| | `SettingsWindowX/Y/Width/Height` | 设置窗口上次的位置(0 = 没记录) |
|
||
| `FloatingButton` | `RefreshIntervalMs` | 悬浮条跟随/条件检查节拍(默认 300ms) |
|
||
| | `Bars[]` | 每条悬浮条:名称、启用、透明度、相对偏移、显示条件(进程/类/标题/导入 path)、按钮列表 |
|
||
| `Commands` | `Triggers[]` | 命令时机(启动/退出/定时/单次)与命令、超时 |
|
||
| `Ocr` | `Enabled` `BaseUrl` `Language` `MinConfidence` `TimeoutSeconds` `SaveScreenshots` `ScreenshotDirectory` | 本地 OCR 服务(**默认关闭**) |
|
||
| `Screenshot` | `Directory` `AllowRestoreMinimized` `RestoreSettleMs` | 截图目录与"是否允许临时恢复最小化窗口" |
|
||
| `Read` | `DefaultTimeoutSeconds` `SkipDisabled` | 无界面读取的默认等待与是否跳过停用条目 |
|
||
|
||
### control-monitors.json(控件监控)
|
||
|
||
```json
|
||
{
|
||
"Version": 1,
|
||
"Items": [
|
||
{
|
||
"Id": "guid",
|
||
"ContentKey": "patient_id", // 别名:结果里的键名,只能字母数字下划线点连字符
|
||
"ControlPath": "/Window[1]//Edit[@AutomationId='PatientId']", // 唯一权威定位
|
||
"Source": "Auto", // Auto / Uia / Msaa / Win32
|
||
"ProcessName": "MyPacs", // 窗口条件(三件套)
|
||
"WindowClass": "PacsMainWindow",
|
||
"WindowTitleKeyword": "工作站",
|
||
"ValueKey": "文本内容",
|
||
"TimeoutSeconds": 0, // 0 = 用 --timeout
|
||
"Disabled": false, // 缺省 = 启用(停用条目无界面模式会跳过)
|
||
"PageFeatures": "可选备注,留空表示不校验页面"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `ControlPath` | 定位唯一权威;匹配 0 个/多个都是明确失败,不会猜 |
|
||
| `Source` | 优先用哪个来源;Auto = UIA → MSAA → Win32 |
|
||
| `ProcessName` / `WindowClass` / `WindowTitleKeyword` | 找顶层窗口的三件套,填了就必须都满足 |
|
||
| `ValueKey` | 读什么(见第 9 层);留空 = 只定位不取值 |
|
||
| `TimeoutSeconds` | 这条自己的等待秒数,0 = 用全局 `--timeout` |
|
||
| `Disabled` | true = 停用(界面上是"启用"复选框的反面) |
|
||
|
||
**旧字段**(只为让老文件还能读出来人工修):`UiaPath`、`MsaaPathKey`、`Win32Path`、`UiaPathFromInnerWindow`。
|
||
新保存不会再写这些,**旧路径格式也不会被执行**(不会静默变成别的东西)。
|
||
|
||
**不落盘的字段**:`RuntimeId`、`Value`、`FocusState`——它们只描述"此刻",写进长期配置会误导。
|
||
|
||
### out.json(无界面读取的结果)
|
||
|
||
`Summary`(Total / Found / Missing / ValueUnavailable / Skipped)+ `Windows[]`(当时的窗口清单)+ `Items[]`
|
||
(每条:`found`、`resolvedSource`、`valueKey`、`value`、`valueAvailable`、`attributes`、`resolution`(逐步诊断)、`error`、`elapsedMs`)。
|
||
|
||
---
|
||
|
||
## 第 9 层:取值键(valueKey)全表
|
||
|
||
跨来源键(三个来源都能选,内部各自映射):
|
||
|
||
| 键 | 含义 |
|
||
|---|---|
|
||
| `文本内容` | 控件的内容文本(UIA:Value→Text→Name;MSAA:accValue→accName;Win32:窗口标题) |
|
||
| `选中状态` | 是/否(列表行、列表项、树节点) |
|
||
| `焦点状态` | 是/否(UIA HasKeyboardFocus / MSAA 状态位 / Win32 比前台窗口) |
|
||
| `列表行数` `列表列数` `列表选中项数` | 容器列表/表格的规模与选中数(UIA) |
|
||
| `选中行文本` | 当前选中那一行的文字(在列表容器上直接读) |
|
||
| `OCR文本` | 截图 + 本地 OCR(需在设置里开启;结果会标注"来自截图识别") |
|
||
|
||
UIA 专用:`Name` `AutomationId` `ControlType` `ClassName` `FrameworkId` `RuntimeId` `IsEnabled` `IsOffscreen`
|
||
`BoundingRectangle` `Value` `Text` `IsSelected` `HasKeyboardFocus`
|
||
|
||
MSAA 专用:`accName` `accValue` `accRole` `accState` `accDescription` `accDefaultAction` `PathKey`
|
||
|
||
Win32 专用:`窗口标题` `类名` `HWND` `窗口矩形` `客户区矩形` `可见` `最小化` `进程名` `PID`
|
||
|
||
> 键是**可手填**的:填了工具不认识的键,会报"该来源不支持的属性名",并列出可用键——不会静默返回空。
|
||
|
||
---
|
||
|
||
## 第 10 层:常见任务怎么做
|
||
|
||
### A. 把一个控件加进监控(30 秒)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["① 选窗口<br/>窗口列表点一下"] --> B["② 选控件<br/>拾取,或在控件树里点节点"]
|
||
B --> C["③ 看下方 Path 横条<br/>确认 XPath"]
|
||
C --> D["④ 监控列表「添加当前控件」<br/>valueKey 默认 文本内容"]
|
||
D --> E["⑤ 点该行「定位到控件」<br/>确认唯一命中 + 画框"]
|
||
E --> F["⑥ 勾「启用」→ 点「保存」"]
|
||
```
|
||
|
||
### B. 盯住"表格现在有几行 / 选中了哪行"
|
||
|
||
1. 选中列表**容器**节点(例如 `DataGrid[FixtureListView]`);
|
||
2. 添加控件后,把 `valueKey` 改成 `列表行数`(或 `列表选中项数`、`选中行文本`);
|
||
3. 要盯"具体某一行"就用行路径:`.../DataItem[@IsSelected='true']` + `文本内容`。
|
||
|
||
### C. 让悬浮条只在某个页面出现
|
||
|
||
1. 设置 → 悬浮按钮 → 新建/选中一条 → 勾「启用」;
|
||
2. 填窗口条件(进程名/窗口类/标题,可下拉选择),或点「导入监控项 path」从已有监控项继承;
|
||
3. 在按钮表格里增加按钮(点击执行什么);
|
||
4. 点「检测显示条件」看诊断:它会把"卡在哪一步"说清楚;
|
||
5. 保存。之后只要条件满足就显示,被别的程序完全遮住或最小化时自动隐藏。
|
||
|
||
### D. 无界面读取(给自动化/脚本用)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["pacs_win_uia.exe --read-saved"] --> B{"已有实例在运行?"}
|
||
B -->|"在"| C["把请求转给它执行<br/>(绝不另开一个实例同步写文件)"]
|
||
B -->|"不在"| D["本进程执行"]
|
||
C --> E["读 control-monitors.json"]
|
||
D --> E
|
||
E --> F["逐条:等窗口 → 定位 → 取值"]
|
||
F --> G["写 out.json(或 stdout)"]
|
||
G --> H{"退出码"}
|
||
H -->|"0"| I["全部命中且取到值"]
|
||
H -->|"1"| J["有未命中 / 取不到值"]
|
||
H -->|"2"| K["参数或配置错误"]
|
||
```
|
||
|
||
常用命令:
|
||
|
||
```bat
|
||
pacs_win_uia.exe --read-saved :: 结果写到 exe 同目录 out.json
|
||
pacs_win_uia.exe --read-config D:\cfg\monitors.json --output - :: 写 stdout
|
||
pacs_win_uia.exe --read-config --timeout 3 --activate --ocr :: 停 3 秒等窗口;先激活无障碍;强制开 OCR
|
||
pacs_win_uia.exe --help
|
||
```
|
||
|
||
### E. 读不到东西时,按这个顺序查
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["先把窗口选对<br/>(窗口列表里能搜到吗)"] --> B["看控件树有没有这个节点<br/>(换来源 / 自动开无障碍 / 检查是否自绘)"]
|
||
B --> C["看 Path 能不能唯一命中<br/>(杂项 → 按 path 定位)"]
|
||
C --> D["看 valueKey 是否合适<br/>(内容在 Name 还是 Value/Text)"]
|
||
```
|
||
|
||
---
|
||
|
||
## 附:三张补充图
|
||
|
||
### 时序图:从按下"拾取控件"到拿到路径
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant M as MainForm
|
||
participant P as CrosshairPicker
|
||
participant T as TargetProbeService
|
||
participant X as 目标程序
|
||
|
||
U->>M: 点「拾取控件」
|
||
M->>M: 隐藏主界面(并记住原前台窗口)
|
||
M->>P: Start()
|
||
P->>P: 显示全屏透明覆盖层 + 低级鼠标钩子
|
||
U->>P: 移动鼠标
|
||
P->>T: 探测光标处的窗口/元素
|
||
T->>X: WindowFromPoint / UIA FromPoint
|
||
X-->>T: 窗口 + 元素 + 矩形
|
||
T-->>P: 蓝框(窗口)+ 黄框(控件链)
|
||
P->>P: 只在鼠标下的框上画标签
|
||
U->>P: 松开左键(点击被钩子吞掉,不会点中目标控件)
|
||
P->>M: Picked(结果)
|
||
M->>M: 恢复主界面并把前台还给原窗口
|
||
M->>M: 从顶层窗口读同一棵树 → 展开并选中该节点
|
||
M->>M: 加入控件监控列表(未启用)+ 显示 Path 横条
|
||
```
|
||
|
||
---
|
||
|
||
### 状态图:悬浮条什么时候显示
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 检查配置
|
||
检查配置 --> 隐藏: 未启用 / 没有启用按钮
|
||
检查配置 --> 找窗口: 有进程名或类名或标题
|
||
找窗口 --> 隐藏: 没有匹配窗口 / 匹配到多个
|
||
找窗口 --> 查XPath: 唯一命中(优先可见窗口,跳过最小化的同名窗口)
|
||
查XPath --> 隐藏: 导入的 XPath 未唯一命中
|
||
查XPath --> 查可见性: 命中
|
||
查可见性 --> 显示: 锚定窗口未被别的程序完全遮住
|
||
查可见性 --> 隐藏: 被别的程序完全遮住 / 最小化
|
||
显示 --> 隐藏: 条件不再满足
|
||
隐藏 --> 找窗口: 下一次节拍(默认 300ms)
|
||
```
|
||
|
||
> 注意:**本工具自己的窗口不算遮挡**——否则在设置页里根本测不了。
|
||
|
||
---
|
||
|
||
### 核心类关系(一页看完)
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class MainForm {
|
||
+三栏界面
|
||
+拾取/定位/绘制框
|
||
}
|
||
class ControlTreeService {
|
||
+Read(hwnd) ControlTreeResult
|
||
}
|
||
class ControlTreeNode {
|
||
+Uia / Msaa / Window
|
||
+Children
|
||
+CanonicalPath
|
||
}
|
||
class ControlPath {
|
||
+Build(root,node)
|
||
+Select(root,xpath)
|
||
+PreparePaths(root)
|
||
}
|
||
class ControlLocatorService {
|
||
+FindTargetWindow(def)
|
||
+Resolve(def,hwnd)
|
||
}
|
||
class ControlValueReader {
|
||
+TryRead(node,valueKey)
|
||
}
|
||
class ControlMonitorStore {
|
||
+Load() / Save()
|
||
}
|
||
|
||
MainForm --> ControlTreeService : 读树
|
||
ControlTreeService --> ControlTreeNode : 产出
|
||
ControlTreeNode --> ControlPath : 算路径
|
||
MainForm --> ControlLocatorService : 回读定位
|
||
ControlLocatorService --> ControlPath : 求值
|
||
ControlLocatorService --> ControlValueReader : 取值
|
||
MainForm --> ControlMonitorStore : 保存配置
|
||
```
|
||
|
||
---
|
||
|
||
## 排错对照表(症状 → 先看哪里)
|
||
|
||
| 症状 | 最可能原因 | 先看 |
|
||
|---|---|---|
|
||
| 控件树只有一行 | 目标没暴露(自绘/未开无障碍) | 第 2 层;状态栏说明;设置里开自动激活 |
|
||
| 树里有节点但拾取不到 | 命中测试给的是容器 | `UiAutomationService.FromHandleAtPoint`(命中后向深处收敛) |
|
||
| Path 匹配 0 个 | 层级变了 / 名字变了 / 选错窗口 | 第 3 层;用 `//` + 稳定祖先 |
|
||
| Path 匹配多个 | 条件太宽 | 加 `@AutomationId` 或祖先范围 |
|
||
| 读到的是标题不是内容 | valueKey 用了 `Name` | 改成 `文本内容` |
|
||
| 列表读不到 | 只有 UIA 的 Grid/Table/遍历 | `ListReaderService`;看它打印的结构诊断 |
|
||
| 悬浮条不显示 | 条件不满足(它会给原因) | 第 6 层状态图 |
|
||
| 界面少了一块 | 控件没加进窗体/没 Dock | 启动日志的"界面布局检查完成:异常区域 N 个" |
|
||
| 启动就崩 | 构造函数里用了还没赋值的字段 | `Program.cs` 的兜底日志 + "构造 MainForm"冒烟 |
|
||
|
||
---
|
||
|
||
## 读代码的顺序(建议)
|
||
|
||
1. `Program.cs` —— 启动分支与单实例;
|
||
2. `Services/ControlTreeService.cs` —— 三来源怎么选;
|
||
3. `Services/ControlPath.cs` —— 路径怎么算、怎么求值;
|
||
4. `Models/ControlTreeNode.cs` —— 一个节点里有什么;
|
||
5. `Services/ControlValueReader.cs` —— 取值键清单与降级;
|
||
6. `UI/MainForm.cs` —— 界面怎么把这些串起来(文件顶部有"要改 X 看哪个方法"的索引)。
|
||
|
||
配套阅读:`docs/代码导览.md`(模块地图 + 坑)、`docs/XPath定位.md`(路径语法与常见问题)。
|