用途
当 .NET MAUI 应用需要处理应用身份资源(图标、启动屏)、打包文件,或需要在启动、停止、恢复及多窗口生命周期事件之间管理状态时,可使用本技能。
主要能力
- 使用 MAUI 单项目项类型管理共享资源:
MauiIcon、MauiSplashScreen、MauiImage、MauiFont、MauiAsset。 - 通过
FileSystem.OpenAppPackageFileAsync访问打包的原始文件。 - 使用跨平台 Window 生命周期事件协调应用与窗口状态。
- 使用
ConfigureLifecycleEvents接入平台特定的生命周期钩子。 - 在停用或停止前持久化用户/会话状态,并在恢复或应用启动时还原。
- 在各目标平台上验证图标、启动屏和背景行为。
资源项类型
<MauiIcon Include="Resources/AppIcon/appicon.svg" ForegroundFile="Resources/AppIcon/appiconfg.svg" Color="#512BD4" />
<MauiSplashScreen Include="Resources/Splash/splash.svg" Color="#512BD4" BaseSize="128,128" />
<MauiImage Include="Resources/Images/*" />
<MauiFont Include="Resources/Fonts/*" />
<MauiAsset Include="Resources/Raw/**" LogicalName="%(RecursiveDir)%(Filename)%(Extension)" />
尽可能使用矢量 SVG 源文件,让 MAUI 生成平台特定尺寸。除非某平台需要自定义覆盖,否则避免手动添加缩放副本。
从 Xamarin.iOS 迁移时,应移除 Platforms/iOS/Info.plist 中旧的 UIAppFonts 条目;MauiFont 会生成这些注册。字体别名应保留在 MAUI 字体管线中,通常通过 MauiFont 项和需要显式别名时的 ConfigureFonts() 实现。不要将 Xamarin Android 的 drawable-* 文件夹或 iOS .xcassets 直接复制到 Platforms/* 中用于 MAUI XAML/C# 的图片;共享图片资源应作为 MauiImage 项放在 Resources/Images 下。
打包资源
将只读打包文件放在 Resources/Raw 中,并使用以下方式打开:
await using var stream = await FileSystem.OpenAppPackageFileAsync("seed.json");
在编辑打包数据之前,先将其复制到应用存储中。应用包中的文件是只读的。
生命周期指导
跨平台 Window 生命周期事件是协调状态的默认位置:
- Created
- Activated
- Deactivated
- Stopped
- Resumed
- Destroying
仅在行为确实依赖原生应用事件(如 Android activity 回调或 iOS scene/app delegate 事件)时,才使用平台生命周期钩子。
状态保持
- 将轻量偏好设置保存在
Preferences中。 - 将较大状态、草稿和缓存保存在应用数据文件或 SQLite 中。
- 在
Stopped或Destroying之前持久化进行中的工作。 - 在
Resumed之后协调过期的网络数据。 - 启用多窗口时,将每个窗口视为具有独立的 UI/导航状态。
- 保持后台工作为平台特定且显式;不要假设应用停止后任意代码会继续运行。
平台配置
| 领域 | 共享默认 | 平台覆盖示例 |
|---|---|---|
| 图标 | MauiIcon |
Android 自适应图标细节、iOS 备用图标元数据 |
| 启动屏 | MauiSplashScreen |
平台启动故事板/主题自定义 |
| 打包文件 | Resources/Raw 中的 MauiAsset |
Platforms/* 下的仅原生文件 |
| 生命周期 | Window 事件 | ConfigureLifecycleEvents 用于原生回调 |
验证清单
- 共享资源使用 MAUI 项类型并位于
Resources下。 - 打包文件通过
FileSystem.OpenAppPackageFileAsync读取。 - 可编辑数据已从应用包中复制出来。
- Xamarin 迁移指导在
MauiFont/ConfigureFonts()拥有共享字体时,移除旧的UIAppFonts/Info.plist字体注册。 - 状态在停止/销毁前保存,并在启动/恢复时还原。
- 平台生命周期钩子隔离于平台特定行为。