简介这是一份基于 Avalonia 的跨平台桌面程序源码包面向希望快速上手 XAML 界面开发与多系统部署的 .NET 开发者项目聚焦 Linux 环境整合 LiveChart2 与 SukiUI并在 Ubuntu 20.04 上完成验证同时解决了默认字体在不同系统下显示不一致的问题。压缩包共 1031 个文件大小约 90.39MB包含 734 个 C# 逻辑代码、211 个 AXAML 界面标记文件以及 ttf/otf 字体、png/ico 图标、csproj/sln 工程配置和多种样式主题定义目录结构清晰便于查阅与二次开发。目前已有 1786 人次学习下载是较受欢迎的 Avalonia 整合示例。资源覆盖基础窗口布局、MVVM 数据绑定、LiveChart2 图表动态更新、SukiUI 控件模板定制等关键知识点并给出 Dashboard、Playground 等综合视图适合用来自上而下学习 XAML 语法、Avalonia 控件组织方式以及跨平台兼容性处理。借助字体配置与多平台工程设置读者可复现作者解决中文与默认字体渲染的思路避开 Linux 桌面应用开发中的常见陷阱。1. Avalonia桌面程序选型一个模板解决“简约可用”的四个卡点“Avalonia桌面程序简约可用整合LiveChart2SukiUI已解决默认字体问题”——这标题看着像堆了三样东西其实它是一类桌面程序的完整骨架一类想用 .NET 做跨平台客户端、又不想背 Electron 内存包袱的人最终都会走到这个组合上来。Avalonia 负责跨平台窗口和控件SukiUI 负责把界面拉回“现代简约”的审美LiveChart2 负责让图表不拖后腿而默认字体问题是中文使用者必经的那道坎——不解决它程序跑起来满屏“豆腐块”再好看的主题也白搭。这篇文章就是把这四个点串成一条可复现的落地路径怎么搭、怎么配、参数设成什么、崩了看哪里、值不值得用。2. 从模板到工程骨架新建项目与最小可运行的结构2.1 模板安装与项目生成别从零手写工程文件Avalonia 有官方项目模板我一般不会手动去建 csproj 和 App 入口直接用 dotnet 模板生成省去把命名空间、启动方式、Avalonia 的 build 任务配错的麻烦。第一步先把模板装进本机。dotnet new install Avalonia.Templates dotnet new avalonia.app -o SimpleDesk cd SimpleDesk dotnet run模板装完再查看本机都有哪些可用模板确认. 我通常会顺手敲一下dotnet new list | grep -i avalonia看看是不是装上了多个变体app、mvvm、x-plat其中avalonia.app是最小的纯 UI 工程不带 MVVM 框架适合我们这种先把界面跑起来的场景。生成出来的工程目录不大核心就几个文件Program.cs、App.axaml、App.axaml.cs、MainWindow.axaml、ViewLocator.cs以及一个Avalonia.Desktop入口项目。注意模板生成后默认的App.axaml里带的是 Fluent 主题后面接 SukiUI 时这个位置要动。第一次dotnet run成功弹出空白窗口说明 SDK 与运行时链路是通的这一步先确认基建没坏再往后加东西。如果你本机环境比较新dotnet run首次恢复包会慢一点耐心等不要中途 CtrlC。2.2 Program.cs 与 App.xaml 启动链路每个文件在管什么Avalonia 最简单也最容易让人困惑的是“到底哪个文件先执行”。我在教别人排错时通常会画一条时间线Main()先跑——它拿到AppBuilder把App类配置进去然后启动桌面生命周期App.axaml.cs的InitializeComponent()加载App.axaml里声明的资源字典、样式和全局设置接着才轮到MainWindow被创建。主线先建立起来字体配置、主题配置、图表控件这些全局性东西才有地方放。using Avalonia; namespace SimpleDesk; internal static class Program { [STAThread] public static void Main(string[] args) BuildAvaloniaApp() .StartWithClassicDesktopLifetime(args); public static AppBuilder BuildAvaloniaApp() AppBuilder.ConfigureApp() .UsePlatformDetect() .LogToTrace(); }这段代码最关键的是BuildAvaloniaApp()这个静态方法——它返回AppBuilder而你后续所有全局级配置字体、平台选项、日志都是在这里通过链式调用 .With() 挂上去的这就是后一章字体全局修复的落点务必记住它。UsePlatformDetect()会根据当前操作系统选择对应的渲染后端和窗口后端Windows 上默认走 DirectXLinux 上走 X11/Wayland 探测macOS 上走 Cocoa你不需要自己判断平台分支。LogToTrace()会把 Avalonia 内部错误输出到调试器或控制台排查数据绑定问题的时候这一句比看断点更直接。2.3 App.axaml 的资源字典结构主题和控件样式的挂载点App.axaml是 Avalonia 里的“全局样式入口”它不是窗口也不是控件而是声明了整个应用共享的资源。模板默认长这样Application.Styles FluentTheme / /Application.Styles这里的FluentTheme是模板自带的跨平台默认主题。SukiUI 这类主题库的接入方式本质上就是拿它们的主题资源替换或叠加到这个节点上这一点先理解到位后面接 SukiUI 时你才知道改的是哪一块。另外注意App.axaml里出现的大部分静态资源会被编译进程序集所以资源字典的加载顺序会影响覆盖关系——排在后面的样式会覆盖前面同 key 的样式。以后如果出现“我改了主题色但部分控件没变”的诡异情况先怀疑是不是有两个资源 ID 冲突了而不是主题库坏了。3. SukiUI 接入让界面在跨平台下保持“简约”观感3.1 为什么选 SukiUI 而不是手写样式一个关于“风格一致性”的取舍把界面做得“简约可用”最大的成本其实不是写控件而是维护一套统一的设计语言——间距、圆角、主题色、暗色模式、字体粗细。手写样式可以从零控制一切但它意味着你要为 Button、TextBox、DataGrid、Card 等几十个控件各写一套样式模板维护成本很快会吞掉那点灵活性。SukiUI 的价值在于它是一套现成的、面向 Avalonia 的现代 UI 主题库把卡片、侧边栏、窗口装饰、控件圆角这些视觉元素统一做掉了你要做的只是选主题色、选暗亮模式再往它提供的容器控件里填内容。用主题库还有一个隐藏好处它同时会把控件默认尺寸、内边距、颜色画刷这类资源一起声明掉等于把设计规范固化成了 XAML 里的键值对。后续某些控件要微调时你不用在几十个 XAML 文件里搜索“原来的蓝色在哪”只需要改对应的画刷资源。对中小团队、个人开发者还有一类项目来说这个收益比“完全自定义”大得多。3.2 在 App.axaml 里注册 SukiUI 主题三步走先通过包管理源安装 SukiUI 包包名就是 SukiUI版本以你当时源里可用的为准然后改App.axaml的 Styles 节点。我把操作拆成三步每一步都有对应代码。Application ... xmlns:sukiclr-namespace:SukiUI;assemblySukiUI Application.Styles suki:SukiTheme / /Application.Styles /Application解析一下这段 XAML 做了什么。xmlns:suki是命名空间映射它告诉 XAML 编译器“suki:”前缀后面的类要往 SukiUI 程序集里找。SukiTheme类是 SukiUI 暴露出来的主题宿主它在初始化时会往应用资源里写入颜色画刷、圆角、控件样式、图标字体等一堆东西相当于一次性完成了 FluentTheme 那个节点的全部工作。注意顺序问题如果同时保留原来的FluentTheme /可能会产生两套控件默认样式而 SukiUI 不一定把每个控件的样式都覆盖干净结果就是部分控件长得像 Suki、部分控件还是 Fluent。我一般直接把 FluentTheme 删掉不搞叠加。然后是在代码里调用主题切换 API。项目启动后通常在主窗口的后台代码里调用它提供的静态方法。SukiUI 的主题对象对应的是暗色/亮色切换以及一组预设主题色的选择。实际调用的方法名以你自己项目引用的版本为准公共模式是“一个切换亮暗静态方法 一个切主题色静态方法”。切主题色的参数通常是预置的颜色枚举比如绿色、蓝色、紫色这些。// 在窗口初始化或设置页面里调用 // 伪代码示意方法名以 SukiUI 当前版本公开 API 为准 SukiTheme.ChangeTheme(Theme.Light); // 切亮色 SukiTheme.ChangeColor(ThemeColor.Blue); // 切主题色为什么我不建议把主题切换做成运行时动态换资源字典因为运行时替换资源字典在很多控件上不会立即刷新——已经构造出来的控件画刷已经被固化到实例属性里了除非所有控件都用 DynamicResource 去引用否则会出现“颜色一半新一半旧”的尴尬。SukiUI 的这套方法会主动触发资源变更通知让引用相关键值的空间来得及刷新。如果你用主题库后发现有控件不跟随切色优先检查那个控件是不是自定义的、有没有用 DynamicResource 绑定颜色键。3.3 主窗口布局用 SukiWindow 和侧边栏撑起“简约可用”的骨架界面骨架我习惯是左侧导航 右侧内容区。SukiUI 提供了专门的窗口和侧边栏容器把主窗口改成 SukiWindow 之后窗口自带的标题栏、阴影、圆角行为都会跟主题走不需要自己画非客户区。下面是一个最小但完整的布局示例把 LiveChart2 图表页面的位置也预留出来。suki:SukiWindow x:ClassSimpleDesk.MainWindow xmlnshttps://schemas.microsoft.com/winfx/2006/xaml/presentation xmlns:xhttp://schemas.microsoft.com/winfx/2006/xaml xmlns:sukiclr-namespace:SukiUI;assemblySukiUI TitleSimpleDesk Width1024 Height680 suki:SukiWindow.Sidebar suki:SukiSidebar StackPanel Margin12 Button Content概览 / Button Content图表 / Button Content设置 / /StackPanel /suki:SukiSidebar /suki:SukiWindow.Sidebar Grid Margin24 TextBlock Text内容区 FontSize28 / /Grid /suki:SukiWindow这个布局里有几个参数值得解释。SukiWindow自带的Sidebar属性是它的核心扩展点它内部把侧边栏的折叠、展开、背景统一处理了而SukiSidebar只是容器里面放什么由你决定放按钮还是放自定义导航控件都行。窗口的主区域默认就是侧边栏右侧的剩余可用空间不需要用 Grid 的 Column 手动分配。如果你不用SukiWindow而是继续用普通 Window 自己画侧栏等于抛弃了主题库最省事的部分——标题栏和窗体边角在跨平台下是最容易出卖“原生感”的地方能用现成的就不自己造。到这里整个界面的“骨架”已经搭起来了观感上已经甩开“裸奔控件”几条街。但一个桌面工具只要涉及数据展示就绕不开图表。下一章把 LiveChart2 接上并且把实时刷新的正确姿势一并讲透。4. LiveChart2 图表整合从静态折线到实时刷新的配置细节4.1 选型理由为什么直接上 LiveChart2 而不是老一代 LiveChartsAvalonia 生态里图表库可选的不多最常见的路线就是 LiveCharts 和 LiveChart2。这里有个命名陷阱LiveCharts 是上一代当时主要针对 WPF/WinForm 设计Avalonia 支持要么残缺要么得走抽象层LiveChart2包名一般带 LiveChartsCore底层基于 SkiaSharp 渲染对 Avalonia 的支持是先在核心库里封装好跨平台绘图逻辑再为每个 UI 框架写一层绑定控件。所以你的图表需求是“能用、能画折线、性能别拖后腿”直接选 LiveChart2 这条线是对的老库的坑太多了别回头踩。它的另一个大优点是 API 密度很低——一张折线图的核心配置不超过十个属性新手看一遍示例就能改出自己的图。这种“配置驱动”的形态很适合咱们后续把图表参数做进配置文件或设置界面。4.2 最小折线图XAML 绑定与 Series 配置先看 XAML 侧的用法。LiveChart2 在 Avalonia 下的控件是CartesianChart命名空间映射到 SkiaSharp 视图层。下面这个例子是一个最简单的单折线图。UserControl ... xmlns:lvcclr-namespace:LiveChartsCore.SkiaSharpView.Avalonia;assemblyLiveChartsCore.SkiaSharpView.Avalonia xmlns:vmclr-namespace:SimpleDesk.ViewModels lvc:CartesianChart Series{Binding ChartSeries} XAxes{Binding XAxes} YAxes{Binding YAxes} / /UserControl对应后台或 ViewModel 里ChartSeries是ISeries[]类型XAxes/YAxes是Axis[]类型。我开始用的时候踩过一个坑Series 绑定用单个对象而不是数组导致图表只有第一根线能画出来后来才意识到 LiveChart2 的Series属性接受的是集合哪怕只有一根线也要包一层数组。using LiveChartsCore; using LiveChartsCore.SkiaSharpView; public partial class ChartView : UserControl { public ISeries[] ChartSeries { get; set; } public Axis[] XAxes { get; set; } public Axis[] YAxes { get; set; } public ChartView() { InitializeComponent(); var values new double[] { 2, 5, 3, 8, 6, 10 }; ChartSeries new ISeries[] { new LineSeriesdouble { Values values, Name 吞吐量, StrokeThickness 2, GeometrySize 4, Fill null } }; XAxes new Axis[] { new Axis { Name 时间, Labels new string[] { T1, T2, T3, T4, T5, T6 } } }; YAxes new Axis[] { new Axis { Name 数值, MinLimit 0 } }; DataContext this; } }几个关键参数我要单独说。StrokeThickness控制线的粗细数值太大会让密集数据段的线条糊成一片我一般默认 2GeometrySize控制数据点圆点的大小窗口较小时设 0 可去掉圆点让线条更干净Fill null是把折线下方默认的渐变填充关掉配合“简约”风格不想要大面积色块时用它。MinLimit 0让 Y 轴从 0 开始而不是从数据最小值开始——这样对比多条线时不会因为坐标起点不同产生视觉误导。记得在InitializeComponent()之后再给 DataContext 赋值顺序反了绑定会在控件加载时才解析经常出现“窗口打开了但图是空的”的假故障其实就是时机问题。4.3 实时更新ObservableCollection 与 Observe 的配合静态折线图只是热身真正制约可用性的是实时数据刷新。很多人在这一步翻车把Values设成一个Listdouble然后定时往里面 Add 数据界面纹丝不动。原因不复杂——LiveChart2 的 Series 并不监听普通集合的增量变化你得让它感知到“数据集合变了”。using System.Collections.ObjectModel; using LiveChartsCore; using LiveChartsCore.SkiaSharpView; using LiveChartsCore.SkiaSharpView.Painting; using SkiaSharp; public partial class RealtimeChartView : UserControl { private readonly ObservableCollectiondouble _cpuValues new(); private ISeries[] _series; private Axis[] _xAxes; public RealtimeChartView() { InitializeComponent(); _series new ISeries[] { new LineSeriesdouble { Values _cpuValues, Name CPU 使用率, Stroke new SolidColorPaint(SKColors.DodgerBlue, 2), GeometrySize 0, Fill null } }; _xAxes new Axis[] { new Axis { Labeler value ${value:F0}s, MinLimit 0, MaxLimit 60 } }; var chart this.FindControlCartesianChart(Chart); chart.Series _series; chart.XAxes _xAxes; } public void AppendSample(double value) { _cpuValues.Add(value); if (_cpuValues.Count 60) _cpuValues.RemoveAt(0); // 关键一步通知图表重新绘制 _series[0].Observe(); _xAxes[0].Observe(); } }这段代码的核心是最后两行Observe()调用。LiveChart2 里ISeries和IAxis都实现了IChartElement它们内部通过一个可观察对象向外广播“我需要重绘”。只改ObservableCollection不调用Observe()图表的绘制缓存不会被标脏于是看起来就像“数据加了但图不动”——这是这块最典型的黑匣子现象。你也可以把Observe()的调用理解成告诉图表“该去重新读一遍数据了”。此外这段代码实现了滚动窗口效果集合里最多保留 60 个采样点超过就移除最旧的X 轴的MinLimit/MaxLimit固定成 0 到 60数据就始终在窗口内左移形成一个经典的时间窗曲线。这种模式在监控、传感器、日志可视化场景里可以直接复抄。4.4 坐标轴与 Tooltip 的对齐细节坐标轴里有几个反直觉的小坑值得单独记一下。Labeler是一个函数接收的是一个 double 类型的坐标值返回字符串作为该坐标的标签。比如采集频率是每秒一次坐标值就是第几秒Labeler里格式化一下变成“12s”这种可读文本。如果你有多个 Series 但共享一个 X 轴轴的MinLimit/MaxLimit要同时满足所有 Series 的数据范围否则会出现某条线被截断在绘图区外的现象而 Y 轴会自适应两条线量级差太大时你需要显式设 Y 轴的MinLimit/MaxLimit否则弱信号那条线会被压成一条直线。Tooltip 方面LiveChart2 默认的十字线提示已经能显示所有 Series 的值不需要额外配置。但如果你的窗口启用了较大的缩放比例Tooltip 的文字有可能变得模糊这是因为默认 Tooltip 走的是 Skia 绘制而非控件文字DPI 适配时会受影响。视觉上出现这种模糊时优先考虑给 Tooltip 加一个TextBrush和Background颜色保证对比度足够不必纠结像素级清晰度这一块属于渲染引擎的取舍。5. 默认字体问题的完整排查现象、根源与全局解法5.1 现象描述与根因为什么中文全是“豆腐块”把 SukiUI 和 LiveChart2 都接好后你很可能在第一次运行的中文界面上看到满屏的方块——这不是字体没装而是 Avalonia 的默认字体不覆盖中文字形。Avalonia 不像传统 UI 框架那样默认使用“系统 UI 字体”它内置的默认字体族名对应的是西文字体当遇到中文字符时它需要到系统字体里去匹配回退字体。问题就出在回退机制上某些系统环境下 Avalonia 的回退匹配返回了不支持中文的字体或者匹配到的字体没有对应字形于是直接画成占位方块。这个现象在 Windows 和 Linux 上表现不同。Windows 上一般会回退到某个中文字体但如果应用里的 font family 被 SukiUI 或你手动设成了一种纯西文字体中文路径就断了Linux 上如果系统没装任何中文字体回退直接失败。所以这不是“字体文件不见了”而是“字体匹配链路断了”。把它当成字体回退问题来处理而不是无脑往程序目录塞字体文件方向才对。5.2 全局修复FontManagerOptions 的配置细节修复的关键在应用启动早期也就是BuildAvaloniaApp()那个入口。Avalonia 提供了FontManagerOptions类用来在全局层面指定默认字族和字体回退策略。using Avalonia; using Avalonia.Media; internal static class Program { [STAThread] public static void Main(string[] args) BuildAvaloniaApp() .StartWithClassicDesktopLifetime(args); public static AppBuilder BuildAvaloniaApp() AppBuilder.ConfigureApp() .UsePlatformDetect() .With(new FontManagerOptions { DefaultFamilyName Microsoft YaHei UI, TryLoadSystemFonts true }) .LogToTrace(); }DefaultFamilyName指定的是整个应用的首选字族名这里写的Microsoft YaHei UI是 Windows 上广泛可用的中文字体名在 Linux 上你可以换成Noto Sans CJK SCmacOS 上可用PingFang SC。这个配置生效后所有没有显式指定 FontFamily 的控件都会优先用这个字族渲染它是全局默认值而不是逐个窗口设置字体。TryLoadSystemFonts的含义是允许 Avalonia 直接访问操作系统安装的字体来做回退匹配把它设成 true 之后即使某段文本用到了默认字族里没有的字形也能从系统字体里找替代。这个属性在不同系统上的默认行为不太一样我一般会显式写成 true避免依赖平台默认值导致跨平台表现不一致。还有一点值得说全局字体配置应该放在AppBuilder.ConfigureApp()之后、StartWithClassicDesktopLifetime之前。顺序错了字体配置可能被应用的初始化资源覆盖掉而这个错不好排查因为不报错只在运行时表现为“好像偶尔有控件没生效”。5.3 高发坑位三个与字体相关的典型翻车场景坑一SukiUI 自带的图标/字体资源把默认字体顶掉了。现象是全局字体配置明明写了但 SukiUI 的 Button、MenuItem 里中文仍显示为方块。原因主题库在加载时会向资源字典注册自己的字体族覆盖了控件默认字体。解决在 SukiUI 的主题资源加载完之后显式对 Button、TextBlock 等控件设 FontFamily 继承链或者把全局 FontFamily 同时写到App.axaml的Application.Resources里作为兜底资源。坑二LiveChart2 图表里的文字不跟随全局字体。现象是界面中文都正常但图表坐标轴标签和 Tooltip 里的中文是方块。原因livechart2 的 Skia 文本绘制不经过 Avalonia 控件样式系统它直接读默认字族来渲染而 Skia 层的默认字族跟 Avalonia 全局字体配置不是同一个来源。解决在 Axis 的LabelsPaint和NamePaint上显式指定字体名称让它使用你配置的中文字体。这类属性是 PAINT 类型例如给LabelsPaint设一个SolidColorPaint并传字体名即可。坑三Linux 上全局字体配了但还是方块。现象是在 Windows 上正常的发布包丢到 Linux 上中文全乱。原因DefaultFamilyName指定的字体名在目标系统上不存在Avalonia 找不到这个字族时回退匹配又没成功。解决检查目标 Linux 系统是否安装了对应字族——用fc-list | grep -i noto.*cjk看一眼如果没有安装中文字体包。这不是代码问题是部署环境的字体缺失问题发布清单里要把“安装中文字体”作为前置依赖写清楚。6. 进阶验证字体回退检查与嵌入字体的交付习惯把字体问题修好只是“本地能跑”真正敢交付还要做一轮跨平台验证。我一般会在每次发布前跑一个固定检查清单如下表盯着最容易在换机器时出问题的三件事。验证项WindowsLinuxmacOS中文列表页/按钮是否无方块看启动后首屏看首屏 弹窗看首屏 弹窗图表 Axis 标签中文是否清晰看 Tooltip 弹出看 Tooltip 弹出看 Tooltip 弹出DPI 125%/150% 下是否模糊设显示缩放后重启常见 1.5x 缩放Retina 默认主题色切换后图表描边颜色是否同步切色后看图例同上同上如果你希望连系统字体都不依赖把字体文件直接打进程序集是更“后悔药”级别的做法——以后换机器、换系统、CI 打包都不用再担心目标环境缺字体。做法是先把字体文件例如一个开源的思源黑体子集放到项目目录然后把FontManagerOptions扩展成把嵌入式字体注册进来。Avalonia 支持直接加载嵌入资源字体配置方式是在FontManagerOptions之外再往AppBuilder挂一个字体源注册步骤。这里不展开具体代码原因是你需要先准备一个你有权再分发的字体文件再按官方字体嵌入机制配置思路是“用 AppBuilder 步骤把嵌入字族注册进全局字体管理器”然后把全局DefaultFamilyName指到这个嵌入字族名上系统字体就只是最后保底不再是唯一依赖。我自己的习惯是做完一个版本先截一张“系统字体环境干净虚拟机”里的运行图再截一张“本机开发环境”的运行图两张摆一起对比字体渲染差别。字体这类问题最容易被“我本机明明好的”掩盖只有环境隔离后才能暴露回退链路的真实状态。这个习惯救过我几次发布事故也希望帮到你。本文还有配套的精品资源点击获取