Files
pacs_win_uia/docs/最小系统.md
T
zimoyin 2c6d2de9f5 新增 docs/最小系统.md:从一条四步链路逐层讲到完整系统(10 张 Mermaid 图)
- 第 0 层最小系统:找窗口 → 读控件树 → 算路径 → 取值
- 逐层展开:窗口匹配分级 / 三来源控件树与自动开无障碍 / XPath 生成与回读 /
  valueKey 降级 / 监控与无界面读取 / 界面三栏与两个浮层 / 周边功能
- 另有时序图(拾取全过程)、状态图(悬浮条何时显示)、类图(核心类关系)、
  排错对照表(症状 → 先看哪里)、读代码顺序
- 顶部说明怎么把 Mermaid 文字渲染成图(VS Code 插件 / Typora / mermaid.live)
- 代码导览顶部加了指向它的链接
2026-10-13 20:33:22 +08:00

14 KiB
Raw Blame History

最小系统(一层层看懂这个工具)

读法:从第 0 层看起,每加一层只多一个概念,配一张图。看完 04 层,这个工具你就懂八成了; 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

一张时序图:从按下"拾取控件"到拿到路径

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"冒烟

读代码的顺序(建议)

  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(路径语法与常见问题)。