capacitor-splash-screen

Capacitor のスプラッシュ画面

使用するタイミング

次の場合に使用します：

• スプラッシュ画面／アイコンのアセットを設定または再生成するとき（npx capacitor-assets generate）
• スプラッシュ画面が消えない、早く消えすぎる、または Web アプリの描画前に白／黒の画面が一瞬表示されるとき
• Android 12 以降で、画像全体ではなく単色背景に小さく切り抜かれたアイコンが表示されるとき
• Capacitor 9 にアップグレードした結果、Android のフェードアウトアニメーションが表示されなくなったとき
• SceneDelegate.swift の追加後、iOS で黒い画面が表示されるとき（8.5 以降）

次の場合は使用しないでください：

• ステータスバー／ナビゲーションバーのスタイル設定と画面端まで表示する場合のインセット：safe-area-handling
• AppDelegate から SceneDelegate への移行：capacitor-uiscene-migration
• 初回描画の遅さ／バンドルサイズ：capacitor-performance
• ストアへの提出に必要なアイコン要件：capacitor-app-store

起動の仕組み（編集する箇所の判断）

フェーズ	iOS	Android 12 以降	Android 11 以前
OS の起動画面（コード実行前）	LaunchScreen.storyboard（UILaunchStoryboardName）、Assets.xcassets/Splash.imageset 内の画像 Splash	システムの SplashScreen API：親が Theme.SplashScreen のテーマ AppTheme.NoActionBarLaunch。アイコンと背景色のみ	androidx.core:core-splashscreen 互換ライブラリ、または android:background ドローアブル
プラグインのスプラッシュ画面（hide() まで）	ブリッジビュー上のプラグインオーバーレイ	API を介して同じシステムのスプラッシュ画面を表示	プラグインの ImageView／Dialog（androidSplashResourceName、androidScaleType）

ほとんどの androidScaleType、showSpinner、splashFullScreen、layoutName、useDialog、backgroundColor オプションは、Android 12 以降の起動時には適用されません（OS が描画するためです）。これらのオプションが反映されるのは、show() の呼び出し時と Android 11 以前のデバイスのみです。

ワークフロー

1. 確認：capacitor.config.* の plugins.SplashScreen、android/app/src/main/res/values/styles.xml、android/variables.gradle（coreSplashScreenVersion）、ios/App/App/Info.plist、ios/App/App/SceneDelegate.swift、assets/ または resources/ フォルダーを確認します。
2. インストール：npm install @capacitor/splash-screen && npx cap sync。
3. アセット：ソースを assets/（icon-only.png、icon-foreground.png、icon-background.png、splash.png、splash-dark.png。スプラッシュ画面は 2732x2732 以上、アイコンは 1024x1024 以上）に配置し、npm install -D @capacitor/assets && npx capacitor-assets generate を実行します（対象を限定するには --ios、--android、--pwa を指定します）。Android 12 以降の円形マスクでロゴが切り取られないよう、ロゴは中央の約 1/3 の範囲に収めます。
4. 意図的に非表示にする：launchAutoHide: false を設定し、最初の意味のある描画が完了した後に hide() を呼び出します（下記参照）。
5. 必要に応じて Android 12 以降を調整： references/android-12-splash.md。
6. 検証（下記参照）。

推奨設定

// capacitor.config.ts
plugins: {
  SplashScreen: {
    launchAutoHide: false,     // hide from JS when the UI is ready
    launchFadeOutDuration: 200, // explicit: Capacitor 9 default on Android is 0
    backgroundColor: '#ffffff', // match the first web paint to avoid a flash
  },
},

import { SplashScreen } from '@capacitor/splash-screen';

// after the router's first view has rendered (e.g. in a root component's mounted/useEffect)
await SplashScreen.hide(); // optional: { fadeOutDuration: 300 }

注意点：

• launchAutoHide: false の場合、hide() の前に JavaScript がクラッシュすると、アプリはスプラッシュ画面から進めなくなります。フォールバックを追加してください：setTimeout(() => SplashScreen.hide(), 8000)。
• 自動非表示の場合のデフォルト値は 500 ms（launchShowDuration）です。固定時間を長くすると、起動が遅く感じられます。固定時間ではなく、準備が整ったタイミングで非表示にしてください。
• <body>／ルートの背景色をスプラッシュ画面の背景色に設定してください。設定しないと、ネイティブのスプラッシュ画面から Web の初回描画までの間に白い画面が一瞬表示されます（ダークモードでは黒）。
• ライブアップデート（capgo-live-updates）では、hide() とは別に notifyAppReady() を呼び出してください。一方の呼び出しをもう一方の呼び出しの条件にしないでください。

バージョンに関する注意

バージョン	変更点
4	Android で Android 12 SplashScreen API と互換ライブラリを使用
7	SplashScreenShowOptions／SplashScreenHideOptions 型を削除し、ShowOptions／HideOptions に変更
8	coreSplashScreenVersion = '1.2.0'
8.5（iOS）	UIScene テンプレートでは SceneDelegate がウィンドウと CAPBridgeViewController を作成します。Main.storyboard はルートビューコントローラーを提供しなくなりました。LaunchScreen.storyboard に変更はなく、引き続き必要です。
9	Android の launchFadeOutDuration のデフォルト値を 200 から 0 に変更（以前のデフォルト値では、hide() の直後の UI 変更がブロックされる場合がありました）。フェードを維持するには、明示的に 200 を設定してください。

iOS に関する注意事項（Capacitor 8.5 以降のシーン）

• Info.plist では UILaunchStoryboardName = LaunchScreen を維持してください。Apple は起動ストーリーボードを必須としているため、削除するとレターボックス表示になったり、サイズが正しく表示されなくなったりします。
• Main.storyboard にビューやカスタムビューコントローラーを追加しても表示されるとは限りません。8.5 の SceneDelegate はコード内で window.rootViewController = CAPBridgeViewController() を設定します。代わりに、カスタムの CAPBridgeViewController サブクラスをそこに設定してください。
• シーンマニフェストがある状態で起動直後に黒い画面が表示される場合、SceneDelegate がウィンドウを作成していない（window = UIWindow(windowScene:) と makeKeyAndVisible() がない）、または UISceneDelegateClassName が存在しないクラスを参照しています。capacitor-uiscene-migration で修正してください。
• ストーリーボードは iOS にキャッシュされます。変更後は、デバイス／シミュレーターからアプリを削除して再インストールしてください。
• サイズ変更可能なウィンドウ／iPad／折りたたみ式デバイスでは、起動ストーリーボードに固定フレームではなく Auto Layout の制約を使用する必要があります（capacitor-ios-resizability がある場合は参照してください）。

検証

1. npx cap sync を実行し、その後ネイティブビルドをクリーンに実行します（Xcode では Product > Clean Build Folder、android/ では ./gradlew clean）。
2. アプリを削除して再インストールします（両プラットフォームとも起動画面がキャッシュされます）。
3. 次の環境でコールド起動します。ライトモードとダークモードの iOS デバイス、Android 12 以降のデバイス、Android 11 以下のエミュレーター（minSdk で許可される場合。Capacitor 9 の minSdk は 26 です）。
4. 次の点を確認します。白／黒のフラッシュがないこと、最初の画面が表示されたらスプラッシュ画面が隠れること、フェードが設定した時間と一致すること。
5. 残っている記述を grep で検索します。

grep -rn "launchFadeOutDuration\|launchAutoHide" capacitor.config.*
grep -n "Theme.SplashScreen\|postSplashScreenTheme" android/app/src/main/res/values/styles.xml
/usr/libexec/PlistBuddy -c "Print :UILaunchStoryboardName" ios/App/App/Info.plist

エラー処理

症状／メッセージ	原因	修正方法
スプラッシュ画面がいつまでも表示される	launchAutoHide: false で、hide() が実行されない（JS エラー、誤ったインポート、プラグインの読み込み前に呼び出している）	Web コンソールを確認し、タイムアウトによるフォールバックを追加します
Capacitor 9 へのアップグレード後、フェードアウトがなくなった（Android）	launchFadeOutDuration のデフォルト値が 0 になりました	launchFadeOutDuration: 200 を設定します
hide() の直後の UI 変更が表示されない（Android、9 より前）	200 ms のフェードによって更新がブロックされています	launchFadeOutDuration: 0 を設定します
Android 12 以降で小さなアイコンが表示され、画像が切り抜かれる	OS のスプラッシュ画面は仕様上アイコンのみです	アダプティブアイコン用のセーフエリアに収まるアートワークを用意し、windowSplashScreenAnimatedIcon を調整します
Android 12／12L で、サードパーティーのランチャーや Android Studio から起動するとスプラッシュ画面が表示されない	Android 13 で修正されたプラットフォームのバグです	標準ランチャーからテストします
error: resource drawable/splash not found	androidSplashResourceName またはスタイルが、存在しないドローアブルを参照しています	アセットを再生成するか、設定と styles.xml の両方で名前を修正します
AAPT: error: style attribute 'attr/windowSplashScreenAnimatedIcon' not found	core-splashscreen 依存関係がありません	implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion" を復元します
8.5 のシーン採用後に iOS で黒い画面が表示される	SceneDelegate でウィンドウが作成されていません	iOS に関する注意事項／capacitor-uiscene-migration を参照してください
iOS で古いスプラッシュ画面が表示される	起動画面のキャッシュ	アプリを削除し、必要であればデバイスを再起動してから再インストールします

リソース

• プラグイン API：https://capacitorjs.com/docs/apis/splash-screen
• スプラッシュ画面とアイコンのガイド：https://capacitorjs.com/docs/guides/splash-screens-and-icons
• 9.0 への更新：https://capacitorjs.com/docs/updating/9-0
• Android SplashScreen API：https://developer.android.com/develop/ui/views/launch/splash-screen