跳到主要內容
版本：v8

@capacitor/splash-screen

啟動畫面 API 提供顯示或隱藏啟動圖片的方法。

安裝​

npm install @capacitor/splash-screen
npx cap sync

Android 12 啟動畫面 API​

這只影響啟動時的啟動畫面，當使用程式化的 show() 方法時不會使用。

Capacitor 4 使用 Android 12 啟動畫面 API 和 androidx.core:core-splashscreen 相容性函式庫，使其在 Android 11 及更低版本上運作。

可以透過將 android/app/src/main/res/values/styles.xml 中 AppTheme.NoActionBarLaunch 的父項從 Theme.SplashScreen 變更為 AppTheme.NoActionBar 來停用相容性函式庫。Android 12 啟動畫面 API 無法在 Android 12+ 上停用，因為它是 Android 作業系統的一部分。

<style name="AppTheme.NoActionBarLaunch" parent="AppTheme.NoActionBar">
    <item name="android:background">@drawable/splash</item>
</style>

注意：在 Android 12 和 Android 12L 裝置上，當從第三方啟動器（如 Nova Launcher、MIUI、Realme Launcher、OPPO Launcher 等）、設定應用程式中的應用程式資訊或 IDE（如 Android Studio）啟動時，不會顯示啟動畫面圖片。Google Issue Tracker Google Issue Tracker Google 已在 Android 13 上修正這些問題，但不會將這些修正反向移植到 Android 12 和 Android 12L。啟動器相關的問題可能會透過啟動器更新來修正。如果仍然發現 Android 13 上與啟動畫面相關的問題，請將它們回報給 Google。

範例​

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

// Hide the splash (you should do this on app launch)
await SplashScreen.hide();

// Show the splash for an indefinite amount of time:
await SplashScreen.show({
  autoHide: false,
});

// Show the splash for two seconds and then automatically hide it:
await SplashScreen.show({
  showDuration: 2000,
  autoHide: true,
});

隱藏啟動畫面​

預設情況下，啟動畫面設定為在 500 毫秒後自動隱藏。

如果您想確保啟動畫面在您的應用程式準備好之前永遠不會消失，請將 launchAutoHide 設定為 false；然後啟動畫面將保持可見，直到手動隱藏。為了獲得最佳的使用者體驗，您的應用程式應盡快呼叫 hide()。

如果您想讓啟動畫面顯示固定的時間長度，請在您的 Capacitor 組態檔案中設定 launchShowDuration。

背景顏色​

在某些情況下，尤其是在啟動畫面沒有完全覆蓋裝置螢幕時，可能會發生應用程式螢幕在角落周圍可見（由於透明度）。您可以設定 backgroundColor 來覆蓋這些區域，而不是顯示透明顏色。

backgroundColor 的可能值為 #RRGGBB 或 #RRGGBBAA。

微調器​

如果您想在啟動畫面頂部顯示微調器，請在您的 Capacitor 組態檔案中將 showSpinner 設定為 true。

您可以使用以下組態自訂微調器的外觀。

對於 Android，androidSpinnerStyle 有以下選項

  • 水平
  • 小
  • large (預設)
  • 反向
  • 小反向
  • 大反向

對於 iOS，iosSpinnerStyle 有以下選項

  • large (預設)
  • 小

若要設定微調器的顏色，請使用 spinnerColor，值為 #RRGGBB 或 #RRGGBBAA。

組態​

這些組態值可用

屬性類型描述預設值起始版本
launchShowDuration數字啟用 autoHide 時，顯示啟動畫面的時間長度（毫秒）5001.0.0
launchAutoHide布林值是否在 launchShowDuration 之後自動隱藏啟動畫面。true1.0.0
launchFadeOutDuration數字啟動畫面淡出動畫的持續時間（毫秒）。僅適用於 Android，當使用 Android 12 啟動畫面 API 時。2004.2.0
backgroundColor字串啟動畫面的背景顏色，採用十六進位格式，#RRGGBB 或 #RRGGBBAA。如果 useDialog 為 true 或在啟動時使用 Android 12 API，則不起作用。1.0.0
androidSplashResourceName字串要用作啟動畫面的資源名稱。當使用 Android 12 API 時，在啟動時不起作用。僅適用於 Android。splash1.0.0
androidScaleType'CENTER' | 'CENTER_CROP' | 'CENTER_INSIDE' | 'FIT_CENTER' | 'FIT_END' | 'FIT_START' | 'FIT_XY' | 'MATRIX'用於縮放啟動畫面圖片的 ImageView.ScaleType。如果 useDialog 為 true 或在啟動時使用 Android 12 API，則不起作用。僅適用於 Android。FIT_XY1.0.0
showSpinner布林值在啟動畫面顯示載入微調器。如果 useDialog 為 true 或在啟動時使用 Android 12 API，則不起作用。1.0.0
androidSpinnerStyle'horizontal' | 'small' | 'large' | 'inverse' | 'smallInverse' | 'largeInverse'Android 微調器的樣式。如果 useDialog 為 true 或在啟動時使用 Android 12 API，則不起作用。large1.0.0
iosSpinnerStyle'small' | 'large'iOS 微調器的樣式。如果 useDialog 為 true，則不起作用。僅適用於 iOS。large1.0.0
spinnerColor字串微調器的顏色，採用十六進位格式，#RRGGBB 或 #RRGGBBAA。如果 useDialog 為 true 或在啟動時使用 Android 12 API，則不起作用。1.0.0
splashFullScreen布林值在啟動畫面隱藏狀態列。當使用 Android 12 API 時，在啟動時不起作用。僅適用於 Android。1.0.0
splashImmersive布林值在啟動畫面隱藏狀態列和軟體導覽按鈕。當使用 Android 12 API 時，在啟動時不起作用。僅適用於 Android。1.0.0
layoutName字串如果 useDialog 設定為 true，則設定對話框版面配置。如果未設定 useDialog 或為 false，則使用版面配置而不是 ImageView。當使用 Android 12 API 時，在啟動時不起作用。僅適用於 Android。1.1.0
useDialog布林值使用對話框而不是 ImageView。如果未設定 layoutName，它將使用以啟動圖片作為背景的版面配置。當使用 Android 12 API 時，在啟動時不起作用。僅適用於 Android。1.1.0

範例​

在 capacitor.config.json 中

{
  "plugins": {
    "SplashScreen": {
      "launchShowDuration": 3000,
      "launchAutoHide": true,
      "launchFadeOutDuration": 3000,
      "backgroundColor": "#ffffffff",
      "androidSplashResourceName": "splash",
      "androidScaleType": "CENTER_CROP",
      "showSpinner": true,
      "androidSpinnerStyle": "large",
      "iosSpinnerStyle": "small",
      "spinnerColor": "#999999",
      "splashFullScreen": true,
      "splashImmersive": true,
      "layoutName": "launch_screen",
      "useDialog": true
    }
  }
}

在 capacitor.config.ts 中

/// <reference types="@capacitor/splash-screen" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    SplashScreen: {
      launchShowDuration: 3000,
      launchAutoHide: true,
      launchFadeOutDuration: 3000,
      backgroundColor: "#ffffffff",
      androidSplashResourceName: "splash",
      androidScaleType: "CENTER_CROP",
      showSpinner: true,
      androidSpinnerStyle: "large",
      iosSpinnerStyle: "small",
      spinnerColor: "#999999",
      splashFullScreen: true,
      splashImmersive: true,
      layoutName: "launch_screen",
      useDialog: true,
    },
  },
};

export default config;

Android​

若要使用名稱不是 splash.png 的啟動畫面圖片，請將 androidSplashResourceName 設定為新的資源名稱。此外，在 android/app/src/main/res/values/styles.xml 中，變更以下區塊中的資源名稱

<style name="AppTheme.NoActionBarLaunch" parent="AppTheme.NoActionBar">
    <item name="android:background">@drawable/NAME</item>
</style>

變數​

此外掛程式將使用以下專案變數（在您應用程式的 variables.gradle 檔案中定義）

  • coreSplashScreenVersion androidx.core:core-splashscreen 的版本（預設值：1.0.1）

範例指南​

新增您自己的圖示和啟動畫面圖片 ›

為 Capacitor (Android) 建立動態/可調整的啟動畫面 ›

API​

show(...)​

show(options?: ShowOptions | undefined) => Promise<void>

顯示啟動畫面

參數類型
選項ShowOptions

起始版本 1.0.0

hide(...)​

hide(options?: HideOptions | undefined) => Promise<void>

隱藏啟動畫面

參數類型
選項HideOptions

起始版本 1.0.0

介面​

ShowOptions​

屬性類型描述預設值起始版本
autoHide布林值是否在 showDuration 之後自動隱藏啟動畫面1.0.0
fadeInDuration數字淡入的時間長度（毫秒）。2001.0.0
fadeOutDuration數字淡出的時間長度（毫秒）。2001.0.0
showDuration數字啟用 autoHide 時，顯示啟動畫面的時間長度（毫秒）30001.0.0

HideOptions​

屬性類型描述預設值起始版本
fadeOutDuration數字淡出的時間長度（毫秒）。在 Android 上，如果使用 Android 12 啟動畫面 API，則不會使用。請改用 launchFadeOutDuration 組態選項。2001.0.0

目錄

編輯此頁面