- 第 8 层:settings.json 各节字段、control-monitors.json 逐字段(含旧字段与 不落盘字段的说明)、out.json 结果结构 - 第 9 层:valueKey 全表(跨来源键 + UIA/MSAA/Win32 各自键),并说明键可手填、 填错会明确报错 - 第 10 层:五个常见任务的照做步骤(加控件 / 盯表格行 / 悬浮条条件 / 无界面读取含退出码流程图 / 读不到的排查顺序) - 时序图、状态图、类图移到文末「附:三张补充图」,0~10 层保持连续好读 - 共 13 张 Mermaid 图
22 KiB
最小系统(一层层看懂这个工具)
读法:从第 0 层看起,每加一层只多一个概念,配一张图。看完 0
4 层,这个工具你就懂八成了; 58 层是界面与周边功能;最后几节是排错对照表和"读代码的顺序"。图都用 Mermaid(文字转图)语法写:
```mermaid代码块里的文字就是图。怎么看到图(任选一种):
- VS Code / Rider:装 Markdown 预览的 Mermaid 插件(VS Code 用 "Markdown Preview Mermaid Support"),预览即可;
- Typora / Obsidian:直接预览;
- 不想装东西:把某个 ```mermaid 代码块的内容贴到 https://mermaid.live 左侧,右侧立刻出图;
- 推送到 GitLab/GitHub 后,网页上会自动渲染。
想改图:直接改代码块里的文字,不用画图工具。
第 0 层:最小系统 = 一条四步链路
整个工具,剥掉所有界面和周边功能,只剩四步:
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 里的控件又没有独立窗口。所以第一步先锁定"哪一棵树"。
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 上的"控件信息"有三套互不相通的体系。工具同时用,按顺序取第一个有内容的:
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:
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 不是内容:
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 层:把上面四步变成"能长期用"
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 层:界面(三栏 + 两个浮层)
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(控件监控)
{
"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 秒)
flowchart LR
A["① 选窗口<br/>窗口列表点一下"] --> B["② 选控件<br/>拾取,或在控件树里点节点"]
B --> C["③ 看下方 Path 横条<br/>确认 XPath"]
C --> D["④ 监控列表「添加当前控件」<br/>valueKey 默认 文本内容"]
D --> E["⑤ 点该行「定位到控件」<br/>确认唯一命中 + 画框"]
E --> F["⑥ 勾「启用」→ 点「保存」"]
B. 盯住"表格现在有几行 / 选中了哪行"
- 选中列表容器节点(例如
DataGrid[FixtureListView]); - 添加控件后,把
valueKey改成列表行数(或列表选中项数、选中行文本); - 要盯"具体某一行"就用行路径:
.../DataItem[@IsSelected='true']+文本内容。
C. 让悬浮条只在某个页面出现
- 设置 → 悬浮按钮 → 新建/选中一条 → 勾「启用」;
- 填窗口条件(进程名/窗口类/标题,可下拉选择),或点「导入监控项 path」从已有监控项继承;
- 在按钮表格里增加按钮(点击执行什么);
- 点「检测显示条件」看诊断:它会把"卡在哪一步"说清楚;
- 保存。之后只要条件满足就显示,被别的程序完全遮住或最小化时自动隐藏。
D. 无界面读取(给自动化/脚本用)
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["参数或配置错误"]
常用命令:
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. 读不到东西时,按这个顺序查
flowchart TD
A["先把窗口选对<br/>(窗口列表里能搜到吗)"] --> B["看控件树有没有这个节点<br/>(换来源 / 自动开无障碍 / 检查是否自绘)"]
B --> C["看 Path 能不能唯一命中<br/>(杂项 → 按 path 定位)"]
C --> D["看 valueKey 是否合适<br/>(内容在 Name 还是 Value/Text)"]
附:三张补充图
时序图:从按下"拾取控件"到拿到路径
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 横条
状态图:悬浮条什么时候显示
stateDiagram-v2
[*] --> 检查配置
检查配置 --> 隐藏: 未启用 / 没有启用按钮
检查配置 --> 找窗口: 有进程名或类名或标题
找窗口 --> 隐藏: 没有匹配窗口 / 匹配到多个
找窗口 --> 查XPath: 唯一命中(优先可见窗口,跳过最小化的同名窗口)
查XPath --> 隐藏: 导入的 XPath 未唯一命中
查XPath --> 查可见性: 命中
查可见性 --> 显示: 锚定窗口未被别的程序完全遮住
查可见性 --> 隐藏: 被别的程序完全遮住 / 最小化
显示 --> 隐藏: 条件不再满足
隐藏 --> 找窗口: 下一次节拍(默认 300ms)
注意:本工具自己的窗口不算遮挡——否则在设置页里根本测不了。
核心类关系(一页看完)
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"冒烟 |
读代码的顺序(建议)
Program.cs—— 启动分支与单实例;Services/ControlTreeService.cs—— 三来源怎么选;Services/ControlPath.cs—— 路径怎么算、怎么求值;Models/ControlTreeNode.cs—— 一个节点里有什么;Services/ControlValueReader.cs—— 取值键清单与降级;UI/MainForm.cs—— 界面怎么把这些串起来(文件顶部有"要改 X 看哪个方法"的索引)。
配套阅读:docs/代码导览.md(模块地图 + 坑)、docs/XPath定位.md(路径语法与常见问题)。