最小系统文档补到 10 层:配置文件字段、valueKey 全表、常见任务步骤

- 第 8 层:settings.json 各节字段、control-monitors.json 逐字段(含旧字段与
  不落盘字段的说明)、out.json 结果结构
- 第 9 层:valueKey 全表(跨来源键 + UIA/MSAA/Win32 各自键),并说明键可手填、
  填错会明确报错
- 第 10 层:五个常见任务的照做步骤(加控件 / 盯表格行 / 悬浮条条件 /
  无界面读取含退出码流程图 / 读不到的排查顺序)
- 时序图、状态图、类图移到文末「附:三张补充图」,0~10 层保持连续好读
- 共 13 张 Mermaid 图
This commit is contained in:
zimoyin
2026-10-13 20:34:24 +08:00
parent 2c6d2de9f5
commit 0e4bccf3f5
+158 -3
View File
@@ -210,7 +210,162 @@ flowchart LR
--- ---
## 一张时序图:从按下"拾取控件"到拿到路径 ## 第 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 ```mermaid
sequenceDiagram sequenceDiagram
@@ -239,7 +394,7 @@ sequenceDiagram
--- ---
## 一张状态图:悬浮条什么时候显示 ### 状态图:悬浮条什么时候显示
```mermaid ```mermaid
stateDiagram-v2 stateDiagram-v2
@@ -260,7 +415,7 @@ stateDiagram-v2
--- ---
## 核心类关系(一页看完) ### 核心类关系(一页看完)
```mermaid ```mermaid
classDiagram classDiagram