跳到正文
PreciSim
source-guide

怎么加一个页面

从零加一个设备调试页,走完 MVVM 的完整套路。

这一篇用一个真实任务把 MVVM 的约定走一遍:加一个「吸嘴真空调试」页。 一个页面 = 一个 View + 一个 ViewModel,两个文件,不多不少。

1. ViewModel

// 07.PreciSim.App/ViewModels/VacuumDebugViewModel.cs
public sealed partial class VacuumDebugViewModel : PageViewModel
{
    private readonly DeviceService _devices;
    private readonly IPermissionGuard _guard;
 
    [ObservableProperty] private bool _vacuumOn;
    [ObservableProperty] private string _message = "";
 
    /// <summary>构造。</summary>
    /// <param name="devices">设备服务。</param>
    /// <param name="guard">权限。</param>
    public VacuumDebugViewModel(DeviceService devices, IPermissionGuard guard)
    {
        ArgumentNullException.ThrowIfNull(devices);
        ArgumentNullException.ThrowIfNull(guard);
        _devices = devices;
        _guard = guard;
    }
 
    /// <inheritdoc/>
    public override string Title => "真空调试";
 
    /// <inheritdoc/>
    public override string NavGroup => "调试";     // 左侧导航分组,顺序见 MainViewModel.NavGroupOrder
 
    [RelayCommand]
    private async Task ToggleVacuumAsync(CancellationToken ct)
    {
        _guard.Demand(UserRole.Engineer);          // 权限在服务/命令入口处校验,不在按钮上
        await _devices.Devices.Io.WriteAsync("VacuumValve", !VacuumOn);
        VacuumOn = !VacuumOn;
    }
 
    /// <inheritdoc/>
    public override Task OnActivatedAsync()        // 页面切到前台;切走用 OnDeactivatedAsync
        => RefreshAsync();
}

要点:

  • 继承 PageViewModel,实现 Title,覆盖 NavGroup 把它放进侧栏的某一组 (运行 / 手动 / 视觉 / 标定 / 设置 / 记录);
  • 没有"只在虚拟设备下可见"的页面:上位机不认识对面是虚拟设备还是真机, 台面视图、故障注入、真值对照都在虚拟设备引擎自己的控制台里;
  • 用 CommunityToolkit.Mvvm 的 [ObservableProperty] / [RelayCommand], 不手写 INotifyPropertyChanged;
  • ViewModel 不 new 设备、不写业务——设备一律经 DeviceService,业务放服务层;
  • 公开类型和成员都要有 XML 注释:TreatWarningsAsErrors 开着,漏了编不过。

2. View

<!-- 07.PreciSim.App/Views/VacuumDebugView.xaml -->
<UserControl x:Class="PreciSim.App.Views.VacuumDebugView"
             xmlns:vm="clr-namespace:PreciSim.App.ViewModels"
             d:DataContext="{d:DesignInstance vm:VacuumDebugViewModel}">
  <StackPanel Margin="16">
    <ToggleButton Content="真空"
                  IsChecked="{Binding VacuumOn, Mode=OneWay}"
                  Command="{Binding ToggleVacuumCommand}" />
    <TextBlock Text="{Binding Message}" />
  </StackPanel>
</UserControl>

要点:

  • 用标准 {Binding},不引入任何绑定 DSL;代码后置只允许 InitializeComponent();
  • 字号 / 字重走 Themes/Shell.xaml 里的键(UiFontSizeTitle / UiFontSize / UiFontSizeSmall / UiFontSizeCaption,页标题用 PageTitle、读数用 Readout 样式),XAML 里不写字面字号; 颜色一律用主题键(Bg2 / Fg / Accent …),深色 / 浅色两套色值字典键名相同;
  • 独立窗口(不是页面)一律继承 AppWindow,深色标题栏是自绘的, 不要自己写 WindowChrome。

3. 注册

// 07.PreciSim.App/App.xaml.cs —— DI
sc.AddSingleton<VacuumDebugViewModel>();
<!-- 07.PreciSim.App/App.xaml —— ViewModel 到 View 的映射 -->
<DataTemplate DataType="{x:Type vm:VacuumDebugViewModel}">
    <v:VacuumDebugView />
</DataTemplate>
// 07.PreciSim.App/ViewModels/MainViewModel.cs —— 构造参数里加一个,再放进页面列表
public MainViewModel(..., VacuumDebugViewModel vacuum)
{
    foreach (var p in new PageViewModel[] { dashboard, jog, io, vacuum, /* … */ }) Pages.Add(p);
}

导航栏是按 NavGroup 自动分组的,不需要另外登记。

4. 导航(没有顶部菜单)

侧栏是唯一的导航:没有顶部菜单栏,也不摆"以后会有"的置灰项。 退出 / 切换用户 / 关于在标题栏右上角的用户菜单里;标定向导从「校正视图」页的"运行向导"进。

5. 界面文案

界面文案目前直接写中文字面量,没有资源文件——这套上位机是单语言的。 要做多语言是一件独立的事,别顺手在页面里搭一半。

6. 跑一遍冒烟

dotnet build PreciSim.sln -c Release
dotnet run --project src/07.PreciSim.App -- --smoke --shot

--smoke 会把所有页面、登录窗、各标定向导窗挨个加载一遍;加 --shot 顺便每个窗口拍一张 PNG 到 out/ui/。XAML 编译通过、绑定不报错,不代表长得对——扫一眼截图比逐个手点快得多。

检查清单

  • ViewModel 里没有 MessageBox(弹窗走 IShellDialogService)
  • ViewModel 里没有 new 出来的设备
  • View 的代码后置只有 InitializeComponent()
  • XAML 里没有字面字号
  • 公开成员都有 XML 注释(否则 Release 编不过)
  • --smoke --shot 跑过,截图看过
最后更新: 2026/9/23
这页有帮助吗?