在MAUI跨平台开发中，App Theming是一套基于资源字典与应用主题状态协同工作的界面换肤体系。它允许开发者在应用运行期间，根据用户选择或系统设置，动态改变整体视觉风格，而不必重建页面对象。理解这套机制，核心是要搞清楚RequestedTheme、UserAppTheme以及MergedDictionaries三者如何配合。
一、MAUI主题系统的基本原理
MAUI在Application层面维护了一个主题状态机。系统通过Application.RequestedTheme暴露当前生效的主题，其值可能是Dark、Light或Unspecified。当值为Unspecified时，应用会跟随操作系统的显示设置；如果开发者显式设置了Application.Current.UserAppTheme，则以用户指定主题为准，覆盖系统行为。
主题切换的视觉落地依赖XAML中的资源字典。MAUI默认在App.xaml里合并了“Light”和“Dark”两套内置字典，框架会根据RequestedTheme自动选用对应字典里的Color与Style。如果我们想扩展自定义主题，只需要准备独立的ResourceDictionary文件，在运行时将其插入或移出App.Current.Resources.MergedDictionaries即可。
1.1 内置主题与系统跟随
新建MAUI项目时，模板已经在App.xaml中引用了如下结构：
<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="DemoApp.App">
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<ResourceDictionary Source="Resources/Styles/Colors.xaml" />
<ResourceDictionary Source="Resources/Styles/Styles.xaml" />
<ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
</Application>
其中Colors.xaml内部通过AppThemeBinding或分文件方式区分浅色与深色。这种方式适合简单场景，但一旦主题数量增加，维护成本会明显上升，因此更推荐将每个主题做成完整字典。
1.2 动态切换的触发点
动态主题切换的本质是改变RequestedTheme或UserAppTheme后，通知所有绑定资源的视觉元素重新取值。MAUI会自动遍历使用DynamicResource的控件并刷新，但若控件使用了静态StaticResource或硬编码画刷，则不会更新。
// 切换到深色主题 Application.Current.UserAppTheme = AppTheme.Dark; // 恢复跟随系统 Application.Current.UserAppTheme = AppTheme.Unspecified;
上述代码执行后，框架内部会引发主题变更事件，页面上绑定了主题资源的元素随之重绘。这也是为什么官方建议所有与主题相关的颜色、样式都通过DynamicResource引用。
二、实现自定义动态主题切换
要实现比官方浅色、深色更丰富的主题，例如“蓝色护眼模式”或“高对比度模式”，可以创建独立的XAML字典，并在代码中控制合并。下面以一个名为BlueTheme.xaml的字典为例。
2.1 准备主题资源字典
在Resources/Styles目录下新建BlueTheme.xaml，定义该主题专用的背景色与文本色：
<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="DemoApp.Resources.Styles.BlueTheme">
<Color x:Key="PageBackgroundColor">#102A43</Color>
<Color x:Key="PrimaryTextColor">#FFFFFF</Color>
<Style TargetType="Label" x:Key="ThemeLabelStyle">
<Setter Property="TextColor" Value="{DynamicResource PrimaryTextColor}" />
</Style>
</ResourceDictionary>
注意这里颜色键名与默认主题保持一致（如PageBackgroundColor），这样在页面XAML中只需统一用DynamicResource引用，切换字典就能整体换色。如果键名不同，页面得写多套绑定，反而复杂。
2.2 在运行时替换字典
我们可以在设置页面提供一个按钮，点击后加载蓝色主题并移除默认深色字典：
private void ApplyBlueTheme()
{
var dictionaries = Application.Current.Resources.MergedDictionaries;
// 移除原有深色主题字典（假设已知实例）
var darkDict = dictionaries.OfType<ResourceDictionary>()
.FirstOrDefault(d => d.Source != null && d.Source.OriginalString.Contains("Dark"));
if (darkDict != null)
{
dictionaries.Remove(darkDict);
}
// 添加自定义蓝色主题
var blueDict = new BlueTheme();
dictionaries.Add(blueDict);
// 强制用户主题不为系统控制
Application.Current.UserAppTheme = AppTheme.Dark;
}
这种方式的优势是无需重启页面，当前栈内页面会自动应用新字典里的DynamicResource。缺点是如果某些第三方控件内部写死颜色，仍然不受控，需要额外重写样式。
三、监听系统主题变化
当用户在手机系统设置里切换浅色或深色时，MAUI应用如果处于Unspecified状态，应当自动跟随。我们可以借助消息机制或重写App的方法来捕获变更。
3.1 使用系统事件
在App构造函数中订阅平台主题变更通知，并弹出提示或记录日志，便于调试：
public App()
{
InitializeComponent();
Microsoft.Maui.Devices.DeviceDisplay.MainDisplayInfoChanged += (s, e) =>
{
var current = Application.Current.RequestedTheme;
System.Diagnostics.Debug.WriteLine("系统主题变为: " + current);
};
}
虽然MAUI会自动处理资源刷新，但有些业务逻辑（例如更换启动图或调整第三方SDK配置）需要感知变更，此时就可以在该事件里编写补偿代码。
3.2 避免常见误区
一个典型错误是在页面后台用BackgroundColor = Brushes.White直接赋值。这样即便主题切换，页面也不会变，因为不是通过资源绑定。正确写法是：
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="DemoApp.MainPage"
BackgroundColor="{DynamicResource PageBackgroundColor}">
<Label Text="动态主题示例"
Style="{DynamicResource ThemeLabelStyle}" />
</ContentPage>
只要所有视觉属性都走DynamicResource，后续无论怎么替换MergedDictionaries或调整UserAppTheme，界面都会平滑过渡，不会出现局部残影。
四、主题切换的性能与最佳实践
动态主题虽好，但频繁整体替换大字典也可能带来微小卡顿。实际项目中建议将主题资源拆分为基础色与组件样式两层，仅替换基础色字典，组件样式保持共用。
4.1 字典分层设计
基础色字典只放Color和Brush，组件样式字典放基于这些色的Setter。切换时只动基础色层：
var baseDict = new BlueColors();
var oldBase = dictionaries.OfType<ResourceDictionary>()
.FirstOrDefault(d => d.GetType().Name == "DarkColors");
if (oldBase != null) dictionaries.Remove(oldBase);
dictionaries.Add(baseDict);
这样可以减少XAML解析量，也方便多人协作：设计师改色，开发改样式，互不干扰。
4.2 持久化用户选择
用户选了深色或蓝色主题后，下次启动应记住。可结合Preferences存储：
// 保存
Preferences.Set("app_theme", "Blue");
// 启动时读取
var saved = Preferences.Get("app_theme", "System");
if (saved == "Blue") ApplyBlueTheme();
通过这种组合策略，MAUI App Theming不仅能做到动态切换，还能兼顾体验一致性与代码可维护性，是跨平台界面个性化的重要基础能力。
MAUIApp_Themingdynamic_theme修改时间：2026-08-01 08:48:37