MENU

.NET MAUIのスプラッシュがAndroid 12以下で真っ白になる原因と解決策（windowBackground・layer-list対応）

C#

.NET MAUIでカスタムスプラッシュを設定しているのに、Android 13以上では表示される一方で、Android 12以下だと起動時に真っ白な画面になってしまう――この差は「OSが参照するスプラッシュの仕組み」がバージョンで違うことが原因です。本記事では、Android 12未満で確実に表示させるための設定と、ハマりやすい確認ポイントを具体例つきで整理します。

目次

.NET MAUIのスプラッシュがAndroid 12以下だけ真っ白になる症状

まず、よくある再現パターンを整理します。Android 13以上（例：Pixel / Android 13、14など）ではスプラッシュ画像が期待通りに表示されるのに、Android 12以下（例：Android 10、11など）ではアプリ起動直後に白い画面（または単色背景）だけが見えて、アイコンやロゴが出ない、という状態です。

.NET MAUI側では、Maui.SplashTheme を継承したテーマを使い、android:windowSplashScreenAnimatedIcon や android:windowSplashScreenBackground などを設定しているのに効かない、という形で気づくことが多いです。

端末 / OS起動時の見え方よくある誤解
Android 13以上ロゴ付きスプラッシュが表示される「設定は正しいはず。Android 10側が不具合？」
Android 12白いまま / デバッグ実行時だけ出ない等の差が出る「Android 12も新APIだから同じはず」
Android 11以下白い背景だけが一瞬表示される（アイコン無し）「windowSplashScreenAnimatedIconが効くはず」

原因はAndroid 12未満が「SplashScreen API」を使わないこと

結論から言うと、Android 12（API 31）で導入された新しいSplashScreen API（windowSplashScreen* 系）と、Android 11以下（API 30以下）の従来の起動描画は仕組みが違います。

Android 12以上は、テーマ内の android:windowSplashScreenAnimatedIcon などの属性をOSが参照して、スプラッシュ画面（アイコン・背景・アニメーション）を描画します。一方で、Android 11以下はこの属性群を参照せず、基本的に android:windowBackground に指定したDrawable が起動画面として表示されます。

Android バージョンOSが主に参照する設定結果として起きること
Android 12以上（API 31+）android:windowSplashScreenAnimatedIcon / android:windowSplashScreenBackground などこれらを正しく設定していればスプラッシュが出る
Android 11以下（API 30-）android:windowBackgroundwindowBackgroundが単色（白など）だと「真っ白」に見える

つまり、Android 13以上でスプラッシュが出ているのにAndroid 10で白いまま、という場合は「Android 10で参照される windowBackground にロゴが入っていない」可能性が非常に高い、ということです。

最短の解決策：Android 12以下向けにwindowBackgroundへlayer-listを直指定する

対策の本丸は、Android 12未満で確実に使われる android:windowBackground を、背景色＋中央アイコンを描画するlayer-list（Drawable XML） に切り替えることです。これで「真っ白（または単色）しか出ない」状態を脱却できます。

やることの全体像

  • styles.xmlで、android:windowBackground の参照先を自作Drawable（layer-list）にする
  • 自作Drawable（layer-list）で、背景色を明示したうえで、中央にアイコン（png等）を置く
  • 参照名（@drawable/xxxx）とファイル名の一致、リソース配置、ビルドアクションを再確認する

手順：styles.xmlのwindowBackgroundを自作Drawableへ変更する

まず、スプラッシュ用テーマ（Maui.SplashTheme を継承したテーマ）に、Android 12未満向けの要として android:windowBackground を設定します。既存で @drawable/maui_splash を指定している場合でも、カスタム構成だと「ロゴが入っていないDrawable」を参照していることがあります。ここを自作のlayer-listに置き換えます。

<?xml version="1.0" encoding="utf-8" ?>
<resources>

  <!-- 例：Maui.SplashThemeを継承してカスタムスプラッシュを定義 -->
  <style name="MySplashTheme" parent="Maui.SplashTheme">

    <!-- Android 11以下（API 30-）で主に使われる：必ず指定する -->
    <item name="android:windowBackground">@drawable/splash_icon</item>

    <!-- Android 12以上（API 31+）で使われる：設定しておく（下位OSは無視される） -->
    <item name="android:windowSplashScreenBackground">@color/splash_background</item>
    <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_logo</item>
    <item name="android:windowSplashScreenAnimationDuration">200</item>

  </style>

</resources>

ここで重要なのが、@drawable/splash_icon のように参照する名前と、実際に作成するファイル名（例：splash_icon.xml）が一致していることです。たとえば splasn_icon.xml のようなタイポが混じると、OSによっては「結果的に白背景だけに見える」など、分かりにくい形で顕在化します。

手順：layer-list（Drawable XML）で背景色＋中央アイコンを明示する

次に、android:windowBackground に指定するDrawableを作ります。ポイントは 背景色を最初のitemで明示し、次のitemで 中央にアイコンを置くことです。背景色を指定しないと、端末やテーマ既定値に引っ張られて意図しない白や透過になり、「真っ白」の印象が強く残ります。

例：Platforms/Android/Resources/drawable/splash_icon.xml

<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">

@drawable/splash_logo はpng等の画像を想定しています。ベクター（VectorDrawable）でも動くケースはありますが、端末依存や変換の問題が出ることがあるため、まずはpngで安定させるのがおすすめです。

手順：リソース配置とビルドアクションを揃える

Androidの起動画面は「最初にOSが参照するリソース」なので、配置ミスやビルドアクションの違いがあると、想定と違う見た目になりやすいです。以下の表のどれかがズレていないかをチェックしてください。

種類配置場所の例（.NET MAUI）ファイル例チェックポイント
テーマ定義Platforms/Android/Resources/values/styles.xmlテーマ名、parent、windowBackgroundの参照先
スプラッシュ用DrawablePlatforms/Android/Resources/drawable/splash_icon.xmllayer-listの先頭で背景色を指定しているか
ロゴ画像Platforms/Android/Resources/drawable/splash_logo.png透過pngの場合、背景色との見え方。解像度不足でボケないか
背景色Platforms/Android/Resources/values/colors.xml@color/splash_backgroundが存在し、色が意図通りか

画像ファイルを追加したら、Visual Studio（またはIDE）上でそのファイルのビルドアクションが AndroidResource になっていることも確認します。ここが違うと、実機では参照できず、結果としてスプラッシュが白く見える原因になります。

手順：テーマの適用先が正しいか確認する（MainActivity / マニフェスト）

設定が正しくても、起動アクティビティにそのテーマが適用されていないと、期待したスプラッシュは出ません。.NET MAUIでは MainActivity の [Activity] 属性でテーマを指定していることが多いので、ここも合わせて確認します。

[Activity(
    Theme = "@style/MySplashTheme",
    MainLauncher = true,
    ConfigurationChanges = ConfigChanges.ScreenSize
        | ConfigChanges.Orientation
        | ConfigChanges.UiMode
        | ConfigChanges.ScreenLayout
        | ConfigChanges.SmallestScreenSize)]
public class MainActivity : MauiAppCompatActivity
{
}

すでに @style/Maui.SplashTheme を指定している場合は、カスタムテーマ名（例：MySplashTheme）に変更したうえで、ビルド→実機で反映されるかを確認します。

Android 12「デバッグ実行時だけスプラッシュが出ない」問題への現実的な対処

Android 12（API 31）では、IDEからのデバッグ起動だとスプラッシュのアイコンが表示されない／一瞬で消える、といった挙動に遭遇することがあります。これはアプリ側のテーマ設定が合っていても起きるケースがあり、ネイティブAndroidでも「起動の仕方」で見え方が変わることがあります。

ただし、今回のようにAndroid 12以下（API 30-）でも真っ白になっている場合は、そもそも windowBackground でロゴを描画していない可能性が高いので、まずはこの記事の対策（layer-listを指定）を優先してください。そのうえで、Android 12での確認は以下の手順が有効です。

  • デバッグを停止したあと、端末の「最近使ったアプリ」から対象アプリを完全終了してから起動する
  • 端末設定から「強制停止」→起動で確認する
  • 一度アンインストールしてから再インストールする（キャッシュ・リソース差分の影響を排除）
  • 可能ならReleaseビルド（またはAPK/AAB）で起動確認する

一見「Android 12の不具合」に見えても、windowBackground を正しく設定し直すことで、デバッグでも安定して表示できるようになることがあります。

よくある失敗例とチェックリスト

スプラッシュが真っ白になるとき、原因は「仕組みの違い」だけでなく、地味な設定ミスが重なっていることもあります。特に下位OSは windowBackground 依存が強いので、以下を順番に潰すのが近道です。

症状原因の候補確認・対処
Android 11以下で白い背景だけwindowBackground が単色で、ロゴが描画されていないwindowBackground をlayer-listにし、背景色＋中央アイコンを定義する
Android 11以下でロゴが出たり出なかったりDrawable名のタイポ（例：splash_iconとsplasn_icon）@drawable/xxxx とファイル名を完全一致させ、余計なファイルを削除する
実機によってロゴが極端に小さい／大きいpngサイズが適切でない、密度別画像が無いdrawable-nodpiを使う／密度別リソースを用意する／BaseSizeを見直す
黒背景の端末で見えない透過png＋背景色が暗い/同化している背景色を変える、ロゴに縁取りを入れる、ダークモード用のリソースを用意する
ビルドは通るが起動時におかしい画像のビルドアクションが AndroidResource ではないファイルのプロパティでビルドアクションを確認し、クリーン→リビルドする

実運用で差が出る：Android 12以上と未満を「リソース分岐」して安全にする

基本は windowBackground をlayer-listにすればAndroid 11以下は安定しますが、プロジェクトの都合で「Android 12以上は新APIの見た目に寄せたい」「Android 11以下は軽量なDrawableだけにしたい」といった要件が出ることもあります。その場合は、Androidのリソース修飾子（-v31）を使ってスタイル自体を分けるのが堅牢です。

例：以下のようにフォルダを分けると、Android 12以上だけ新APIの属性を含むスタイルを定義できます。

  • Platforms/Android/Resources/values/styles.xml（全OS共通 / 旧OS用の最小構成）
  • Platforms/Android/Resources/values-v31/styles.xml（Android 12以上のみ上書き）

旧OS側（values/styles.xml）は windowBackground だけに絞るとシンプルです。

&lt;resources&gt;
  &lt;style name="MySplashTheme" parent="Maui.SplashTheme"&gt;
    &lt;item name="android:windowBackground"&gt;@drawable/splash_icon&lt;/item&gt;
  &lt;/style&gt;
&lt;/resources&gt;

Android 12以上側（values-v31/styles.xml）で、windowSplashScreen* を追加します。

&lt;resources&gt;
  &lt;style name="MySplashTheme" parent="Maui.SplashTheme"&gt;
    &lt;item name="android:windowBackground"&gt;@drawable/splash_icon&lt;/item&gt;
    &lt;item name="android:windowSplashScreenBackground"&gt;@color/splash_background&lt;/item&gt;
    &lt;item name="android:windowSplashScreenAnimatedIcon"&gt;@drawable/splash_logo&lt;/item&gt;
    &lt;item name="android:windowSplashScreenAnimationDuration"&gt;200&lt;/item&gt;
  &lt;/style&gt;
&lt;/resources&gt;

この構成にしておくと、Android 11以下では余計な属性の影響を受けず、Android 12以上では新APIでの表現も活かせます。

確認のコツ：真っ白＝クラッシュではなく「何も描画していない」サイン

スプラッシュが真っ白でも、アプリがクラッシュしていないなら、OSが描画するべきリソースを「白（単色）」として解釈している可能性が高いです。特に以下の2つは見落としがちです。

  • 背景色が明示されていない（透過Drawableや、テーマ既定の白に依存している）
  • ロゴが描画される場所が定義されていない（windowSplashScreenAnimatedIconだけに頼っている）

Android 11以下では windowSplashScreenAnimatedIcon が効かないため、ロゴを見せたいなら windowBackground 側（layer-list）でロゴを描画する、という考え方が必要になります。

まとめ：Android 12以下対策の中心はwindowBackground、次にタイポ潰し

  • Android 11以下は新しいSplashScreen API（windowSplashScreen*）を参照しないため、android:windowBackground が実質的なスプラッシュになる
  • windowBackground を背景色＋中央アイコンのlayer-listにして、真っ白問題を解消する
  • 参照名とファイル名の不一致（タイポ）、リソース配置、ビルドアクションを徹底的に確認する
  • Android 12のデバッグ起動は見え方が変わることがあるため、冷起動やReleaseでの確認も併用する
C#
.NET MAUI Android 12 スプラッシュ windowBackground layer-list

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次