Avalonia Pro Max 组件配方是一套面向 Avalonia UI 的 XAML 样式与控件用法示例,目标是帮助开发者快速搭建生产质量的桌面应用界面。所有配方都假定项目已加载 avalonia-pro-max/design-system 提供的设计令牌,例如 SurfaceBrush、AccentBrush、TextPrimaryBrush、RadiusLg、Space* 等,这些令牌通过 StaticResource 或 DynamicResource 引用。
主要能力按组件划分:
按钮:提供可复用的按钮样式(Styles/Buttons.axaml),通过 Classes 使用 primary、secondary、ghost icon、danger、primary lg 等变体。图标按钮需要设置 AutomationProperties.Name 以保证无障碍。
卡片:使用 Border.card 样式,包含 SurfaceElevatedBrush 背景、1 像素边框、RadiusLg 圆角和 PaddingCard 内边距;附加 interactive 类实现鼠标悬停时阴影过渡。
分组控件:Avalonia 12.0+ 可直接使用内置 GroupBox(HeaderedContentControl)实现带标题的分组;11.3 中不存在 GroupBox,需沿用 Border.card 加标题 TextBlock 的模式。
只读表格:12.1+ 推荐内置 TableView(派生自 ListBox,虚拟化,支持 Columns、CanUserResizeColumns、ItemsSource 绑定);DataGrid 在 12.x 处于维护模式,仅在需要编辑、排序 UI 或层级结构时使用 DataGrid 或 TreeDataGrid,或在不具备 TableView 的版本中使用。表格样式与列表一致:行高不小于 36 像素、边框式表头使用 TextMutedBrush、1 像素行分隔线,宽数据才考虑斑马纹。
侧边导航:FluentAvalonia 应用使用 NavigationView,可配置 PaneDisplayMode、OpenPaneLength、菜单项与页脚菜单项,并通过 Frame 承载内容;非 FluentAvalonia 应用可用 SplitView 加 ListBox 自建侧边栏。
应用外壳:示例展示 ExtendClientAreaToDecorationsHint、ExtendClientAreaTitleBarHeightHint、TransparencyLevelHint 与 ExperimentalAcrylicBorder 组合的自定义标题栏,并注明 12 版本中 ExtendClientAreaChromeHints 被移除、SystemDecorations 被 WindowDecorations 替代等版本差异。
对话框:使用 FluentAvalonia ContentDialog 实现模态确认框,可设置默认按钮并通过 PrimaryButtonClick 事件处理确认逻辑,破坏性操作可用危险样式。
表单校验:示例展示带标签、占位符、辅助文本与错误文本的表单;错误状态通过 TextBox:error 伪类自动应用;12.0+ 使用 PlaceholderText,11.x 使用 Watermark;配合 ViewModel 的 INotifyDataErrorInfo。
其它组件:空状态(居中图标、标题、说明与主按钮)、Toast 通知(WindowNotificationManager 与 Notification)、徽章(圆角标签,可切换成功、警告、危险、静默状态)、骨架屏(透明度关键帧动画)以及 FluentAvalonia SettingsExpander 设置行。
使用方式:将样式放入 Styles/Buttons.axaml 等文件,在各视图中通过 Classes 和设计令牌引用;组件代码为 XAML 或 C# 片段,可直接粘贴到项目中并按版本调整。
限制与注意事项:配方依赖 design-system 令牌,未加载时资源引用会失败;不同 Avalonia 版本控件可用性不同(如 GroupBox 仅 12.0+、TableView 仅 12.1+、PlaceholderText 仅 12.0+);图标按钮需补充无障碍名称;仅用红色反馈校验错误不够,应结合辅助文本;页内卡片应使用 ShadowSm 或 1 像素边框,避免与高层级阴影混用;非阻塞提示应使用 Toast 而非 ContentDialog。