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. 02SVG のビルド時描画問題の解決
  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 のアルファ値が無視され、代わりに黒で表示されます。


<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 を使用する — ファイルが 1 つで、無限に拡大縮小でき、リポジトリのサイズも小さくなります。
  2. SVG の viewBox が希望する論理サイズと一致しない場合は、BaseSize を明示的に設定する。
  3. スプラッシュ画像はシンプルにする — 大きい SVG や複雑な 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 に Color が設定された MauiIcon 項目がある
  • .csproj に Color と BaseSize が設定された MauiSplashScreen 項目がある
  • Android：セーフゾーンに適合させるため、ForegroundScale を指定した合成アイコンを使用している
  • SVG のソースがシンプルである（グラデーション／フィルターなし）、または Resize="false" を指定した PNG の代替画像を使用している
  • 画面密度と切り抜きを確認するため、エミュレーターだけでなく実機でもテストしている

コメント

Markdown 対応