diff --git a/docs/最小系统.md b/docs/最小系统.md index 8f43f1f..a0c20f4 100644 --- a/docs/最小系统.md +++ b/docs/最小系统.md @@ -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["① 选窗口
窗口列表点一下"] --> B["② 选控件
拾取,或在控件树里点节点"] + B --> C["③ 看下方 Path 横条
确认 XPath"] + C --> D["④ 监控列表「添加当前控件」
valueKey 默认 文本内容"] + D --> E["⑤ 点该行「定位到控件」
确认唯一命中 + 画框"] + 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["把请求转给它执行
(绝不另开一个实例同步写文件)"] + 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["先把窗口选对
(窗口列表里能搜到吗)"] --> B["看控件树有没有这个节点
(换来源 / 自动开无障碍 / 检查是否自绘)"] + B --> C["看 Path 能不能唯一命中
(杂项 → 按 path 定位)"] + C --> D["看 valueKey 是否合适
(内容在 Name 还是 Value/Text)"] +``` + +--- + +## 附:三张补充图 + +### 时序图:从按下"拾取控件"到拿到路径 ```mermaid sequenceDiagram @@ -239,7 +394,7 @@ sequenceDiagram --- -## 一张状态图:悬浮条什么时候显示 +### 状态图:悬浮条什么时候显示 ```mermaid stateDiagram-v2 @@ -260,7 +415,7 @@ stateDiagram-v2 --- -## 核心类关系(一页看完) +### 核心类关系(一页看完) ```mermaid classDiagram