mcpField
M
maui-app-icons-splash

maui-app-icons-splash

github.com/davidortinau设计与 UI17652 次安装16 周前更新
代码仓库

关于 maui-app-icons-splash

.NET MAUI 图标与启动屏幕设计技能，面向配置跨平台应用资源的开发者。它汇总 Android 自适应图标安全区、SVG 缩放及构建问题的实践建议。

主要功能

  1. 01图标与启动屏幕配置检查
  2. 02Android 自适应图标安全区建议
  3. 03SVG 与 PNG 资源排错
  4. 04BaseSize 尺寸配置提示
  5. 05真机测试清单

适用场景

  1. 01排查图标显示为空或被裁切
  2. 02解决 SVG 构建渲染问题
  3. 03修正特定平台的图标尺寸
  4. 04检查项目启动屏幕配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/davidortinau/maui-skills --skill maui-app-icons-splash

安装后在 Claude Code 中输入/maui-app-icons-splash确认已加载。

附带文件references/icons-splash-api.md

详细介绍

.NET MAUI 应用图标与启动屏幕

常见问题

❌ Android 自适应图标被裁切

Android 自适应图标会裁切为圆形或圆角方形安全区域。如果前景填满画布，就会被裁切。


<MauiIcon Include="Resources\AppIcon\appicon.svg"
          Color="#512BD4" />


<MauiIcon Include="Resources\AppIcon\appicon.svg"
          ForegroundFile="Resources\AppIcon\appiconfg.svg"
          ForegroundScale="0.65"
          Color="#512BD4" />
❌ 启动屏幕的 Color 透明

某些平台会忽略启动屏幕 Color 中的 alpha 值，并显示黑色。


<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#00FFFFFF" />


<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#512BD4" />
❌ 混淆 Color 与 TintColor
  • Color = 图标或启动屏幕后方的背景填充色。
  • TintColor = 重新着色前景图像本身。

如果只设置 TintColor，而没有可见的前景路径，图标就会空白。

⚠️ 构建时 SVG 渲染问题

包含渐变、滤镜或蒙版的复杂 SVG，可能无法通过 Microsoft.Maui.Resizetizer MSBuild 任务正确栅格化。


<MauiIcon Include="Resources\AppIcon\appicon.png"
          Resize="false" />
⚠️ BaseSize 不匹配

如果 SVG 的 viewBox 与所需逻辑尺寸不匹配，请明确设置 BaseSize，否则输出尺寸可能不正确。


<MauiIcon Include="Resources\AppIcon\appicon.svg"
          BaseSize="456,456"
          Color="#512BD4" />

最佳实践

  1. 尽可能使用 SVG——一个文件、无限缩放、更小的代码仓库。
  2. 当 SVG 的 viewBox 与所需逻辑尺寸不匹配时，明确设置 BaseSize。
  3. 保持启动屏幕图像简单——大型或复杂的 SVG 会拖慢构建速度，还可能产生渲染瑕疵。
  4. 在真实设备上测试——模拟器的屏幕密度会掩盖图标裁切问题，尤其是 Android 自适应图标的安全区域问题。
  5. 为 Android 使用组合图标——ForegroundFile + ForegroundScale="0.65" 可确保前景位于安全区域内。

快速故障排查

现象可能的解决方法
图标显示为空白或白色检查 Color 与 TintColor；确保存在 SVG 路径
启动屏幕显示默认 .NET 徽标确认 .csproj 中包含 MauiSplashScreen 项
Android 图标看起来被裁切使用 ForegroundScale="0.65" 的组合图标
SVG 导致构建错误简化 SVG，或改用 Resize="false" 的 PNG
图标在某个平台上的尺寸不正确在 .csproj 中明确设置 BaseSize

检查清单

  • .csproj 中存在 MauiIcon 项，且已设置 Color
  • .csproj 中存在 MauiSplashScreen 项，且已设置 Color 和 BaseSize
  • Android：使用组合图标，并通过 ForegroundScale 确保符合安全区域要求
  • SVG 源文件简单（无渐变或滤镜），或使用 Resize="false" 的 PNG 作为备用
  • 已在真实设备（而非仅在模拟器）上测试屏幕密度和裁切情况

评论

支持 Markdown