スプラッシュスクリーン

このコア機能は、Webアプリケーションの起動中にプラットフォームのスプラッシュスクリーンを設定および制御する機能を提供します。

• スプラッシュスクリーン
  • サポートされているプラットフォーム
  • プラットフォームのスプラッシュスクリーン画像の設定
    • 設定例
    • Android固有の情報
      • Androidの設定例
    • iOS固有の情報
      • 起動ストーリーボード画像
        • 起動ストーリーボード画像の設計
        • スケール
        • イディオム
        • サイズクラス
        • 単一画像の起動画面
        • 複数画像の起動画面
        • ダークモード
  • config.xmlの設定
    • AutoHideSplashScreen
    • FadeSplashScreen
    • FadeSplashScreenDuration
    • ShowSplashScreenSpinner
    • SplashScreenDelay
    • AndroidPostSplashScreenTheme
    • AndroidWindowSplashScreenAnimatedIcon
    • AndroidWindowSplashScreenAnimationDuration
    • AndroidWindowSplashScreenBackground
    • AndroidWindowSplashScreenBrandingImage
    • AndroidWindowSplashScreenIconBackgroundColor
  • JavaScriptパブリックAPI
    • navigator.splashscreen.hide
    • navigator.splashscreen.show
  • 癖と既知の問題
    • iOS
    • Android

サポートされているプラットフォーム

• Android
• iOS

他のプラットフォームについては、`cordova-plugin-splashscreen`のサポートを確認してください。

プラットフォームのスプラッシュスクリーン画像の設定

設定例

トップレベルの`config.xml`ファイル（`platforms`にあるものではありません）に、ここで指定されているような設定要素を追加します。

"src"属性の値は、プロジェクトのルートディレクトリからの相対パスであり、`www`ディレクトリからの相対パスではありません（以下の「ディレクトリ構造」を参照）。ソース画像ファイルには任意の名前を付けることができます。アプリケーション内の内部名はCordovaによって自動的に決定されます。

ディレクトリ構造

projectRoot
    platforms
    plugins
    www
    res
        screen
            android
            ios

Config.xml

<platform name="android">
    <preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/splashscreen.xml" />
</platform>

<!--
  Storyboard (supports all devices):
  Note: images are determined by scale, idiom, and size traits. The following
  are suggested based on current device form factors
-->
<platform name="ios">
    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comcom.png" />
    <splash src="res/screen/ios/Default@3x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@3x~universal~anycom.png" />
    <splash src="res/screen/ios/Default@3x~universal~comany.png" />
</platform>

Android固有の情報

Android 12以降、GoogleはAndroid 12以降を搭載したデバイスで実行されるアプリの起動アニメーションを制御するための新しいSplashScreen APIを実装しました。下位互換性のために、Cordovaには、この機能をAndroid API 21以降に拡張する`core-splashscreen`互換性ライブラリが含まれています。

独自のAndroid SplashScreenアセットを効果的に作成するには、アダプティブアイコンの要件を理解することが重要です。

リソース

• スプラッシュスクリーンの寸法
• アダプティブアイコン

Androidの設定例

<platform name="android">
    <!-- Default -->
    <preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/splashscreen.xml" />
</platform>

iOS固有の情報

起動ストーリーボード画像は、スケール、イディオム、およびサイズクラスに基づいてサイズ設定されます。すべてのデバイスをサポートし、分割画面/スライドオーバーマルチタスキングで使用できます。

iPad Pro 12.9にネイティブ解像度の起動画像を提供したり、分割画面マルチタスキングまたはスライドオーバーで動作する起動画像を提供したりするための公式のサポートはありません。

**注記:** iOS 11以降、iPhone X以降のデバイス（ノッチ画面付き）では、`index.html`ファイルのビューポートメタタグに`viewport-fit=cover`を追加して、アプリが正しく表示されるようにしてください。例：`<meta name="viewport" content="user-scalable=no, initial-scale=1, width=device-width, viewport-fit=cover">` また、`index.css`ファイルに`padding: env(safe-area-inset-top)`を追加してアプリのスタイルを変更し、画面のノッチの背後にある安全でない領域を回避してください。

起動ストーリーボード画像

新しいフォームファクターと分割画面/スライドオーバーマルチタスキングをサポートするために、起動ストーリーボード画像が使用されます。

• 画像は特定のデバイスに固有のものではありません。
• 画像は、利用可能なビューポートに合わせて拡大縮小されます（アスペクト比は維持されます）。
• 画像の外側のエッジはトリミングされ、その量はデバイスとビューポートによって異なります。
• 考えられるすべてのデバイス、ビューポート、および向きに画像を提供する必要はありません。 iOSは状況に最適な画像を自動的に選択します。

起動ストーリーボード画像の設計

起動ストーリーボード画像を設計する際の鍵は、画像のエッジがほぼ確実にトリミングされることを理解することです。したがって、提供された起動ストーリーボードの画像のエッジ付近に重要な情報を配置しないでください。中央だけが安全な領域であり、これは、Appleのアドバイスに従って、空のユーザーインターフェイスを表示することがうまく機能しないことをほぼ保証します。

代わりに、次のヒントに従うことで、さまざまなフォームファクター、ビューポート、および向きで機能する起動イメージを作成できます。

• 重要なグラフィック（ロゴ、アイコン、タイトル）は中央に配置する必要があります。安全な境界領域は異なるため、重要なグラフィックがトリミングされないことを確認するためにテストする必要があります。さらに良いのは、そもそも重要なグラフィックを提供しないことです。

  • これらのグラフィックの配置とサイズを微調整*できます*。

• シンプルなカラーウォッシュを使用してください。2色を使用する場合は、一方の色で画像の上半分を塗りつぶし、もう一方の色で下半分を塗りつぶします。グラデーションを使用する場合は、グラデーションの中央が画像の中央に揃っていることを確認することをお勧めします。

• ピクセルパーフェクトについて心配しないでください。画像は拡大縮小されるため、画像がピクセルグリッドに完全にフィットする可能性はほとんどありません。サポートされているすべてのiOSデバイスはRetinaスクリーンを使用しているため、ユーザーはとにかく気付くのに苦労するでしょう。

起動ストーリーボード画像を効果的に使用するには、スケール、イディオム、およびサイズクラストレイトの概念を理解することが重要です。起動ストーリーボードに提供された画像の中から、iOSはデバイスとビューポートに最も一致する画像を選択し、その画像をレンダリングします。必要に応じて起動画像を1つだけ提供することもできますが、トレイトに基づいて表示される起動画像を微調整することもできます。微調整を行う場合は、アプリでターゲットにされていない、またはサポートされていないトレイトを無視できます。

スケール

一般的に、2倍および3倍の画像を提供することをお勧めします。Cordovaは現在Retinaデバイスのみをサポートしているため、1倍の画像を提供しても意味がありません。

イディオム

特定のデバイスイディオムに合わせて微調整する必要がある場合を除き、ユニバーサル画像を提供するだけで済みます。

サイズクラス

両方の画面軸に適用される2つのサイズクラスがあります。狭いビューポートは「コンパクト」サイズクラスと見なされ、残りのビューポートは「レギュラー」と見なされます。ただし、Xcodeに画像を提供する場合、「任意＆コンパクト」と「任意＆レギュラー」のどちらかを選択する必要があります。ネイティブの用語と一致させるために、この機能は「任意」と「コンパクト」に基づいて一致します。`任意`はレギュラーサイズのビューポートと一致します。

注：この機能は、「コンパクト」クラスの略語として`com`を使用します。

この機能では、次のクラスがサポートされています。

単一画像の起動画面

起動画像が単純な場合は、多くの異なる起動画像を作成することを避け、1つだけ提供できる場合があります。起動画像は次の要件を満たしている必要があります

• 画像は正方形である必要があります
• 画像はiPad Pro 12.9インチに収まるのに十分な大きさである必要があります：2732x2732
• 重要なものはすべて中央に収まる必要があります

ビューポートによっては、画像が非常に大きくトリミングされる可能性があることに注意してください。

画像が作成されたら、`config.xml`に以下を追加することで、プロジェクトに含めることができます。

    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />

画像が1つしか提供されていないため、iOSはすべてのコンテキストでそれを使用します。

複数画像の起動画面

単一の起動画像ではニーズを満たせない場合は、少なくとも6つ以上の画像を提供する必要があるでしょう。さらに、特定のデバイスではなく、デバイスクラス、表示係数、およびビューポートサイズにのみ画像を微調整できることに注意してください。

特定のイディオムに画像をターゲットにする必要がない場合は、次のように6つの画像を作成する必要があります。

*この画像は、iOSがこのスケールとイディオム内の他の画像を利用するために必要です。

注：3倍のサイズが小さすぎるように見える場合は、現在3倍の密度を持つデバイスクラスがiPhone 6+/6s+/7+のみであるためです。

上記は、`config.xml`に存在する場合、次のスニペットのようになります。

    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comcom.png" />
    <splash src="res/screen/ios/Default@3x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@3x~universal~anycom.png" />
    <splash src="res/screen/ios/Default@3x~universal~comany.png" />

デバイスイディオムに基づいてさらに微調整する必要がある場合は、そうすることができます。これは次のようになります。

*この画像は、iOSがこのスケールとイディオム内の他の画像を利用するために必要です。

上記は、`config.xml`では次のようになります。

    <splash src="res/screen/ios/Default@2x~iphone~anyany.png" />
    <splash src="res/screen/ios/Default@2x~iphone~comany.png" />
    <splash src="res/screen/ios/Default@2x~iphone~comcom.png" />
    <splash src="res/screen/ios/Default@3x~iphone~anyany.png" />
    <splash src="res/screen/ios/Default@3x~iphone~anycom.png" />
    <splash src="res/screen/ios/Default@3x~iphone~comany.png" />
    <splash src="res/screen/ios/Default@2x~ipad~anyany.png" />
    <splash src="res/screen/ios/Default@2x~ipad~comany.png" />

ダークモード

Cordova-iOS@6.1.0以降、アプリがダークモードで実行されているときに使用する異なるSplashScreen画像をオプションで指定できるようになりました。 SplashScreen画像の輝度は、`~dark`および`~light`サフィックスを使用して`config.xml`で定義できます。

<!-- Default image to be used for all modes -->
<splash src="res/screen/ios/Default@2x~universal~anyany.png" />

<!-- Image to use specifically for dark mode devices -->
<splash src="res/screen/ios/Default@2x~universal~anyany~dark.png" />

<!-- Image to use specifically for light mode devices -->
<splash src="res/screen/ios/Default@2x~universal~anyany~light.png" />

**注記:**これはiOS 13以降で動作します。iOS 12以前では、輝度サフィックスが指定されていないデフォルトのSplashScreenが使用されます。

config.xmlの設定

AutoHideSplashScreen

スプラッシュスクリーンを自動的に非表示にするかどうかを示します。スプラッシュスクリーンは、`SplashScreenDelay`設定で指定された時間が経過すると非表示になります。

サポートされているプラットフォーム

• Android
• iOS

**データ型:** `ブール値`

**デフォルト値:** `true`

使用例

<preference name="AutoHideSplashScreen" value="true" />

FadeSplashScreen

スプラッシュスクリーンのフェードインとフェードアウトの機能を制御します。

Androidの場合、フェードアウトのみを制御します。

サポートされているプラットフォーム

• Android
• iOS

**データ型:** `ブール値`

**デフォルト値:** `true`

使用例

<preference name="FadeSplashScreen" value="false"/>

FadeSplashScreenDuration

スプラッシュスクリーンのフェードエフェクトの長さを制御します。

サポートされているプラットフォーム

• Android
• iOS

データ型: Float、ミリ秒単位

デフォルト値: 500

使用例

<preference name="FadeSplashScreenDuration" value="750"/>

iOSの注意: FadeSplashScreenDuration は SplashScreenDelay に含まれます。例えば、config.xml に <preference name="SplashScreenDelay" value="3000" /> と <preference name="FadeSplashScreenDuration" value="1000"/> が定義されている場合、

• 00:00 - スプラッシュスクリーンが表示されます
• 00:02 - フェードアウトが開始されます
• 00:03 - スプラッシュスクリーンが非表示になります

<preference name="FadeSplashScreen" value="false"/> を使用してフェードアウトをオフにすると、技術的にはフェードアウトの時間が 0 になるため、この例ではスプラッシュスクリーンの全体的な遅延は依然として3秒になります。

注意: これはアプリケーションの起動時にのみ適用されます。アプリケーションのコードでスプラッシュスクリーンを手動で表示/非表示にする場合は、フェードアウトのタイムアウトを考慮する必要があります。

navigator.splashscreen.show();
window.setTimeout(function () {
    navigator.splashscreen.hide();
}, splashDuration - fadeDuration);

ShowSplashScreenSpinner

スプラッシュスクリーンのスピナーを制御します。

サポートされているプラットフォーム

• iOS

**データ型:** `ブール値`

**デフォルト値:** `true`

使用例

<preference name="ShowSplashScreenSpinner" value="false"/>

SplashScreenDelay

スプラッシュスクリーンを自動的に非表示にするまでの待機時間（ミリ秒単位）。

サポートされているプラットフォーム

• Android
• iOS

データ型: Number、ミリ秒単位

**デフォルト値:** `true`

• Android -1: onPageFinished がトリガーされると、スプラッシュスクリーンは自動的に非表示になります。

• iOS 3000: スプラッシュスクリーンは3秒後に自動的に非表示になります。

使用例

<preference name="SplashScreenDelay" value="3000" />

AndroidPostSplashScreenTheme

スプラッシュスクリーンが非表示になった後のアクティビティのポストテーマを設定します。

注意: この設定は利用可能ですが、自己責任で使用してください。

サポートされているプラットフォーム

• Android

データ型: String

デフォルト値: @style/Theme.AppCompat.NoActionBar

使用例

<preference name="AndroidPostSplashScreenTheme" value="@style/Theme.AppCompat.NoActionBar"/>

AndroidWindowSplashScreenAnimatedIcon

スプラッシュスクリーンの画像。この設定は、アニメーションアイコンと非アニメーションアイコンの両方に使用されます。現在受け入れ可能なアセットファイルは、XMLベクタードローアブルまたはPNGです。

:warning: アダプティブアイコンを使用するには、最小SDKを26に設定する必要があります。

:warning: 一部のXMLベクター機能を使用するには、最小SDKを24に設定する必要があります。

サポートされているプラットフォーム

• Android

データ型: String、アセットファイルへのファイルパス

デフォルト値: 指定されていない場合は、Cordovaのデフォルトアセットが使用されます。

使用例

<preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/splashscreen.xml" />

AndroidWindowSplashScreenAnimationDuration

アニメーションベクタードローアブルがスプラッシュスクリーン画像として提供されている場合、アイコンのアニメーション時間を定義します。

サポートされているプラットフォーム

• Android

データ型: Number、ミリ秒単位

デフォルト値: undefined（未定義）

使用例

<preference name="AndroidWindowSplashScreenAnimationDuration" value="3000"/>

AndroidWindowSplashScreenBackground

スプラッシュスクリーンの背景色。

サポートされているプラットフォーム

• Android

データ型: String、カラー16進コード値。

デフォルト値: #ffffff

使用例

<preference name="AndroidWindowSplashScreenBackground" value="#ffffff" />

AndroidWindowSplashScreenBrandingImage

:warning: この設定は現在サポートされていません。Cordova Androidが後方互換性を提供するために依存しているcore-splashscreen互換性ライブラリは、この機能を実装していません。Google Android Issue Trackerを参照してください

AndroidWindowSplashScreenIconBackgroundColor

スプラッシュスクリーンのアイコンの背景色。背景とアイコンのコントラストを上げるのに役立ちます。

サポートされているプラットフォーム

• Android

データ型: String、カラー16進コード値。

デフォルト値: undefined（未定義）

使用例

<preference name="AndroidWindowSplashScreenIconBackgroundColor" value="#c0c0c0" />

JavaScriptパブリックAPI

navigator.splashscreen.hide

スプラッシュスクリーンを閉じます。

サポートされているプラットフォーム

• Android
• iOS

使用例

navigator.splashscreen.hide();

iOSの特異性

config.xml ファイルの AutoHideSplashScreen 設定は false でなければなりません。スプラッシュスクリーンの非表示を2秒遅延させるには、deviceready イベントハンドラに次のようなタイマーを追加します。

setTimeout(function() {
    navigator.splashscreen.hide();
}, 2000);

navigator.splashscreen.show

スプラッシュスクリーンを表示します。

サポートされているプラットフォーム

• iOS

使用例

navigator.splashscreen.show();

アプリケーションが起動し、deviceready イベントが発生するまで、アプリケーションは navigator.splashscreen.show() を呼び出すことができません。しかし、通常、スプラッシュスクリーンはアプリケーションが起動する前に表示されることを意図しているため、スプラッシュスクリーンの目的を無効にするように見えるかもしれません。 config.xml にパラメータを指定すると、アプリケーションの起動直後、アプリケーションが完全に起動して deviceready イベントを受信する前に、スプラッシュスクリーンが自動的に show されます。このため、アプリケーションの起動時にスプラッシュスクリーンを表示するために navigator.splashscreen.show() を呼び出す必要はほとんどありません。

癖と既知の問題

iOS

1. iOSでは、スプラッシュスクリーン画像は起動画像と呼ばれます。これらの画像はiOSでは必須です。

2. ターゲット上のアプリは画像の変更を反映しない場合があります ターゲットでアプリを実行すると、iOSは起動画像をキャッシュします。残念ながら、画像を変更しても、iOSはキャッシュを無効に*しません*。つまり、古い起動画像が表示されたままになります。アプリを削除するか、コンテンツと設定をリセットする（シミュレータ）必要があります。

3. **CLIから起動した場合、シミュレータは予期される画像を表示しない場合があります** Xcodeが特定のシミュレータにデプロイする場合、シミュレータの特性に一致するアセットのみがコピーされます。たとえば、iPhone 6s Plusシミュレータでアプリを実行しようとすると、@3x起動画像のみがコピーされます。ただし、CLIからコンパイルする場合、デフォルトではiPhone 5sと想定されるため、@2x起動画像のみがコピーされます。起動画像に大きな違いがない限り、違いに気付かない可能性がありますが、これは、正確なテスト方法は物理デバイスでテストすることだけであることを意味します。

4. 他のバリエーションを使用するには、`anyany` を提供する必要があります 特定のスケールとイディオムの `anyany` バージョンの起動画像を提供しない場合、他のバリエーション（`anycom`、`comany`、`comcom` など）は無視されます。

Android

1. Android 12では、Android StudioまたはCordova CLIからアプリケーションを起動すると、スプラッシュスクリーンが表示されません。これは既知のAndroid 12の問題です。アプリをデバイスまたはシミュレータにアップロードし、終了してアプリを開くと、スプラッシュスクリーンが表示されます。変更が表示されない場合は、クリーンビルドも実行してみてください。これはAndroid 13で修正されています。