Axi_Omron/docs/superpowers/specs/2026-04-16-axi-omron-ui-design.md

Axi Omron PCB Check - UI 美化设计文档

目标

将 AxiOmron.PcbCheck 的 WPF 界面引入 HandyControl (3.5.1) 进行美化，视觉风格与参考程序（Daimler_PCB_Check_Client）保持一致，降低后续维护成本。

当前状态

• 项目为 .NET 8 WPF 应用，当前无第三方 UI 库。
• 主要界面文件：
  • MainWindow.xaml：顶部标题栏 + 两个导航按钮 + Frame 容器。
  • Views/Pages/DashboardPage.xaml：状态卡片、操作按钮、日志表格、最近处理记录。
  • Views/Pages/SystemSettingsPage.xaml：TabControl 配置表单。
• 参考程序已使用 HandyControl 3.5.1，并采用 SkinDefault 主题 + PrimaryBrush 等内置资源。

设计细节

1. 引入 HandyControl 包

• 在 AxiOmron.PcbCheck.csproj 中添加 PackageReference Include="HandyControl" Version="3.5.1"。
• 在 App.xaml 的 Application.Resources 中合并两个资源字典：
  • pack://application:,,,/HandyControl;component/Themes/SkinDefault.xaml
  • pack://application:,,,/HandyControl;component/Themes/Theme.xaml
• 引入 HandyControl 命名空间 xmlns:hc="https://handyorg.github.io/handycontrol" 到需要使用高级控件的页面（如主窗口）。

2. MainWindow.xaml

• 标题栏：背景改用 DynamicResource {x:Static hc:ResourceToken.PrimaryBrush}（与参考程序一致）。
• 标题文字：字号 20、白色、加粗、左边距 20。
• 导航按钮：使用 Style="{StaticResource ButtonPrimary}"（参考程序样式），字号 18、加粗、适当内边距，保持“首页 / 系统设置”两个按钮。
• 窗口尺寸：保持现有 Width=1600 / Height=950 / MinWidth=1400 / MinHeight=860，居中启动。
• Frame 容器：不变，继续承载 DashboardPage 与 SystemSettingsPage。

3. DashboardPage.xaml

• 页面背景：移除硬编码 #0F172A，改由外层窗口/页面背景统一，或显式设为 {DynamicResource {x:Static hc:ResourceToken.BackgroundBrush}}。
• 操作按钮：将现有自定义 PrimaryButtonStyle 替换为 HandyControl 的 ButtonPrimary，保持命令绑定不变。
• 状态卡片：
  • 将现有 Border 卡片样式替换为 HandyControl 的 Card（hc:Card）或保留 Border 但统一使用主题色。
  • 推荐做法：使用 hc:Card，设置 BorderThickness="0"，内部保持 StackPanel + TextBlock 结构。
  • 标题字体：16-18，加粗；数值字体：14-16。
• 数据表格：
  • 日志 DataGrid 与最近处理记录 DataGrid 保留，但移除硬编码行背景色、前景色、边框色，使用系统默认或浅色主题下的 DataGrid 样式。
  • 列宽与绑定不变。
• 流程状态区：将“流程状态”卡片改为 hc:Card 高亮展示，错误信息使用红色文字（不变）。

Dashboard 下半区布局方案确认

• 已确认采用 方案 A：双栏中枢布局。
• 设计目标：
  • 消除当前页面下半区的大面积空白。
  • 强化“当前板状态”和“过程追踪”两个核心视觉中心。
  • 将运行日志降为辅助信息，而不是和主业务区争抢注意力。
• 布局原则：
  • 左侧承担“当前状态 + 运行日志”主视角，右侧承担“处理记录 + 追踪摘要”副视角。
  • 下半区不再平均切成多个小卡片，而是改为“少块、大面、强层级”。
  • 通过不同卡片高度、标题层级、留白和分组，建立更清晰的信息优先级。

Dashboard 下半区具体布局

• 整体分栏：
  • 下半区采用 1.3 : 0.9 左右双栏。
  • 左栏为主工作区，右栏为过程追踪区。
• 左栏上部：
  • 使用两个并排摘要卡片。
  • 卡片 1：当前二维码 + 结果码 / 报警码
  • 卡片 2：关键标志 + 扫码次数 + SFTP 次数
  • 当前二维码信息作为左栏上部的第一视觉重点，字体明显大于普通统计值。
• 左栏下部：
  • 放置 最近运行日志，占据左栏主要高度。
  • DataGrid 保留，但应提升表头、行高、内边距和空状态表现，避免“开发态表格感”过强。
• 右栏上部：
  • 放置 最近处理记录摘要，展示：
    • 最近触发时间
    • 最近完成时间
    • 最后刷新时间
  • 该区域应做成信息摘要卡，而不是散落的三行文字。
• 右栏下部：
  • 放置 最近处理记录列表。
  • 列表可以保留 DataGrid，但视觉上应更轻，重点突出时间、条码、结果三列。
  • 若 HandyControl 样式允许，可适当弱化网格线，提升卡片式整洁感。

Dashboard 下半区视觉风格约束

• 不新增花哨装饰，不改为互联网运营后台风格，保持工业桌面应用的稳重感。
• 卡片层次应依靠以下手段建立，而不是依赖过多边框：
  • 标题字号差异
  • 数值字号差异
  • 卡片阴影和圆角
  • 区块留白
  • 轻量分隔
• 关键标志 建议改为更有秩序的纵向状态列表，保留圆点语义，但需统一间距、字号、对齐。
• 结果码 / 报警码 不再作为独立弱卡片存在，应并入主摘要区，提高信息密度。
• 最近处理记录 与 最近运行日志 必须形成主次关系：
  • 主日志区更宽，更适合排查问题。
  • 处理记录区更紧凑，更适合回看节拍与结果。

本次改造范围

• 仅重构 DashboardPage.xaml 的下半区布局与视觉层级。
• 不修改 ViewModel 属性命名、命令绑定和业务逻辑。
• 不新增复杂动画、主题切换、图表控件或第三方可视化组件。
• 若需要新增局部样式或页面资源，应优先放在页面内，避免污染全局资源。

4. SystemSettingsPage.xaml

• TabControl：使用 HandyControl 的 TabControl 样式（默认已覆盖），或显式使用 hc:TabControl。
• 表单项：
  • 将大量 Label + TextBox 组合替换为 hc:TextBoxExtend，设置 hc:InfoElement.Title="标题" 和 hc:InfoElement.TitlePlacement="Left"。
  • 这样可以去掉自定义 FieldLabelStyle 和 FieldTextBoxStyle，减少代码量。
  • 每个 Tab 内部保持 ScrollViewer + Grid 两列布局（标题列 + 输入列）。
• 复选框：使用 CheckBox 即可，HandyControl 已提供默认样式。
• 底部操作栏：保留“重新加载 / 保存配置”两个按钮，样式改为 ButtonPrimary 和 ButtonDefault（或保持默认），与参考程序一致。

5. 数据绑定与代码影响

• 所有 ViewModel 命令、属性绑定保持不变。
• 不需要修改 .cs 文件，除非控件类型变更导致需要调整命名引用（如 Border -> hc:Card 不影响后台代码）。
• 自定义 BooleanToBrushConverter 继续保留并在 DashboardPage 使用。

6. 构建与验证

• 添加包后执行 dotnet restore。
• 编译项目，确认无 XAML 资源加载异常。
• 启动应用，检查：
  1. 主窗口标题栏颜色与按钮样式正常。
  2. Dashboard 卡片、表格显示正常，无布局错位。
  3. SystemSettings 各 Tab 表单输入框带有 HandyControl 样式（圆角、焦点效果）。
  4. 各页面切换无异常。

排除项（本次不做）

• 不改写业务逻辑、ViewModel、服务层。
• 不引入 HandyControl 的高级控件（Growl、Timeline、Pagination 等），避免过度设计。
• 不替换为其他 UI 库（MahApps、MaterialDesign、WPFUI 等）。