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
这页有帮助吗?