啟動畫面

這個核心功能讓您能夠在您的 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 實作了新的 SplashScreen API 來控制在 Android 12 及更高版本的裝置上執行的應用程式啟動動畫。為了向後相容性，Cordova 包含了 core-splashscreen 相容性程式庫，將此功能擴展回 Android API 21 及更高版本。

為了有效地建立您自己的 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 加入 viewport meta 標籤，以正確顯示應用程式，例如：<meta name="viewport" content="user-scalable=no, initial-scale=1, width=device-width, viewport-fit=cover">，並對您的應用程式樣式進行一些修改，方法是將 padding: env(safe-area-inset-top) 加入您的 index.css 檔案，以避免螢幕瀏海後面的不安全區域。

啟動故事版圖片

為了支援更新的外觀規格和分割畫面/滑動覆蓋多工處理，使用了啟動故事版圖片。

• 圖片不是針對特定裝置的。
• 圖片會縮放以填滿可用的視窗 (同時保持長寬比)。
• 圖片的外邊緣會被裁剪，並且裁剪量會因裝置和視窗而異。
• 無需為每個可能的裝置、視窗和方向提供圖片；iOS 會自動選擇最適合情況的圖片。

設計啟動故事版圖片

設計啟動故事版圖片的關鍵是了解圖片的邊緣幾乎肯定會被裁剪。因此，不應將任何重要資訊放置在提供給啟動故事版的任何圖片的邊緣附近。只有中心是安全區域，這幾乎可以保證遵循 Apple 的建議呈現未填充的使用者介面不會很好地工作。

相反，以下提示應能讓您建立適用於多種外觀規格、視窗和方向的啟動圖片

• 重要的圖形（標誌、圖示、標題）應居中。安全的邊界區域會有所不同，因此您需要進行測試以確保重要的圖形永遠不會被裁剪。更好的是，一開始就不要提供任何重要的圖形。

  • 您可以微調這些圖形的位置和大小。

• 使用簡單的色彩沖刷。如果您使用兩種顏色，您會希望一種顏色填滿圖片的上半部分，第二種顏色填滿下半部分。如果您使用漸層，您可能需要確保漸層的中間與圖片的中心對齊。

• 不要擔心像素完美 -- 因為圖片會縮放，所以幾乎不可能使圖片完美適合像素網格。由於所有支援的 iOS 裝置都使用視網膜螢幕，因此使用者很難注意到它。

為了有效地使用啟動故事版圖片，了解縮放、慣用語和尺寸類別特性的概念非常重要。在提供給啟動故事版的圖片中，iOS 會選擇最符合裝置和視窗的圖片並呈現該圖片。如果需要，可以只提供一張啟動圖片，但也可以根據特性微調顯示的啟動圖片。在微調時，可以忽略應用程式未定位或不支援的特性。

縮放

一般來說，您會希望提供 2x 和 3x 圖片。Cordova 現在只支援視網膜裝置，因此提供 1x 圖片毫無意義。

慣用語

除非您需要針對特定裝置慣用語進行微調，否則您只需要提供通用圖片。

尺寸類別

有兩個尺寸類別會同時應用於螢幕軸。窄視窗被視為「壓縮」尺寸類別，其餘視窗被視為「一般」尺寸類別。但是，在將圖片提供給 Xcode 時，必須在「任何 & 壓縮」和「任何 & 一般」之間選擇。為了與原生術語保持一致，此功能將根據「任何」和「壓縮」進行匹配。any 將匹配一般大小的視窗。

注意：此功能使用 com 作為「壓縮」類別的縮寫。

此功能支援以下類別

單一圖片啟動畫面

如果您的啟動圖片很簡單，您或許可以避免建立許多不同的啟動圖片，而只提供一張。啟動圖片需要符合以下需求

• 圖片應該是正方形
• 圖片應該夠大，可以容納在 iPad Pro 12.9" 上：2732x2732
• 任何重要的內容都應該在中心範圍內

請記住，圖片會被裁剪，並且可能會根據視窗嚴重裁剪。

建立圖片後，您可以透過將以下內容加入 config.xml 來將其包含在您的專案中

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

因為只提供一張圖片，所以 iOS 會在每個環境中使用它。

多圖片啟動畫面

如果單一啟動圖片無法滿足您的需求，您可能需要至少提供六張圖片，甚至更多。此外，請記住，無法將圖片微調到特定裝置，而只能微調到裝置類別、顯示因子和視窗大小。

如果您不需要將圖片定位到特定慣用語，您應該建立六張圖片，如下所示

* 為了讓 iOS 利用此縮放和慣用語中的其他圖片，必須要有此圖片。

注意：如果 3x 大小看起來太小，那是因為目前只有一個裝置類別具有 3x 密度：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，現在可以選擇性地指定在應用程式在深色模式下執行時要使用的不同啟動畫面圖片。可以使用 ~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 及更低版本將使用未指定亮度後綴的預設啟動畫面。

config.xml 偏好設定

AutoHideSplashScreen

指出是否自動隱藏啟動畫面。啟動畫面會在 SplashScreenDelay 偏好設定中指定的時長後隱藏。

支援的平台

• Android
• iOS

資料類型： Boolean

預設值： true

使用範例

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

FadeSplashScreen

控制啟動畫面淡入和淡出的能力。

對於 Android，它僅控制淡出。

支援的平台

• Android
• iOS

資料類型： Boolean

預設值： 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

資料類型： Boolean

預設值： true

使用範例

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

SplashScreenDelay

自動隱藏啟動畫面之前等待的時間（以毫秒為單位）。

支援的平台

• Android
• iOS

資料類型： Number，單位為毫秒

預設值： true

• Android -1：當 onPageFinished 被觸發時，啟動畫面將自動隱藏。

• iOS 3000：啟動畫面將在 3 秒後自動隱藏。

使用範例

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

AndroidPostSplashScreenTheme

設定啟動畫面隱藏後 Activity 的後續佈景主題。

注意：此設定可用，但請自行承擔使用風險。

支援的平台

• 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，顏色十六進位碼值。

預設值： #ffffff

使用範例

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

AndroidWindowSplashScreenBrandingImage

:warning: 此設定目前不受支援。Cordova Android 用來提供向後相容性的核心啟動畫面相容性程式庫尚未實作此功能。請參閱 Google Android 問題追蹤器

AndroidWindowSplashScreenIconBackgroundColor

啟動畫面圖示的背景顏色。有助於增加背景和圖示之間的對比度，以便區隔開來。

支援的平台

• Android

資料類型： String，顏色十六進位碼值。

預設值： undefined

使用範例

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

JavaScript 公開 API

navigator.splashscreen.hide

關閉啟動畫面。

支援的平台

• Android
• iOS

使用範例

navigator.splashscreen.hide();

iOS 特性

config.xml 檔案的 AutoHideSplashScreen 設定必須為 false。若要延遲隱藏啟動畫面兩秒鐘，請在 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 Studio 或 Cordova CLI 啟動應用程式時，Android 12 不會顯示啟動畫面。 這是 Android 12 已知的問題。將應用程式上傳到裝置或模擬器後，退出並開啟應用程式將會顯示啟動畫面。如果未顯示變更，請嘗試執行清除建置。此問題已在 Android 13 中修正。