跳到主要内容
版本：v7

@capacitor/splash-screen

Splash Screen API 提供了显示或隐藏启动画面图像的方法。

安装​

npm install @capacitor/splash-screen@latest-7
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 等）、设置应用中的应用信息或 Android Studio 等 IDE 启动时，启动画面图像不会显示。 Google Issue Tracker Google Issue Tracker Google 已在 Android 13 上修复了这些问题，但不会将修复程序回溯到 Android 12 和 Android 12L。 与启动器相关的问题可能会通过启动器更新得到修复。 如果您在 Android 13 上仍发现与启动画面相关的问题，请向 Google 报告。

示例​

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

// 隐藏启动画面（您应该在应用启动时执行此操作）
await SplashScreen.hide();

// 无限期显示启动画面：
await SplashScreen.show({
  autoHide: false,
});

// 显示启动画面两秒后自动隐藏：
await SplashScreen.show({
  showDuration: 2000,
  autoHide: true,
});

隐藏启动画面​

默认情况下，启动画面设置为在 500 毫秒后自动隐藏。

如果您想确保启动画面在应用准备好之前不会消失，请将 launchAutoHide 设置为 false；启动画面将保持可见直到手动隐藏。为获得最佳用户体验，您的应用应尽快调用 hide()。

相反，如果您想固定时间显示启动画面，请在您的 Capacitor 配置文件中设置 launchShowDuration。

背景颜色​

在某些情况下，特别是当启动画面没有完全覆盖设备屏幕时，应用屏幕可能会在角落处可见（由于透明度）。您可以设置 backgroundColor 来覆盖这些区域，而不是显示透明颜色。

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

加载指示器​

如果您想在启动画面上显示加载指示器，请在您的 Capacitor 配置文件中将 showSpinner 设置为 true。

您可以使用以下配置自定义加载指示器的外观。

对于 Android，androidSpinnerStyle 有以下选项：

  • horizontal
  • small
  • large（默认）
  • inverse
  • smallInverse
  • largeInverse

对于 iOS，iosSpinnerStyle 有以下选项：

  • large（默认）
  • small

要设置加载指示器的颜色，请使用 spinnerColor，值为 #RRGGBB 或 #RRGGBBAA。

配置​

以下配置值可用：

属性类型描述默认值自从
launchShowDurationnumber当 autoHide 启用时，启动时启动画面显示的时间（毫秒）5001.0.0
launchAutoHideboolean是否在 launchShowDuration 后自动隐藏启动画面。true1.0.0
launchFadeOutDurationnumber启动时启动画面淡出动画的持续时间（毫秒）。仅适用于 Android，使用 Android 12 启动画面 API 时。2004.2.0
backgroundColorstring启动画面背景颜色，十六进制格式 #RRGGBB 或 #RRGGBBAA。如果 useDialog 为 true 或启动时使用 Android 12 API 则无效。1.0.0
androidSplashResourceNamestring用作启动画面的资源名称。启动时使用 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
showSpinnerboolean在启动画面上显示加载指示器。如果 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
spinnerColorstring加载指示器的颜色，十六进制格式 #RRGGBB 或 #RRGGBBAA。如果 useDialog 为 true 或启动时使用 Android 12 API 则无效。1.0.0
splashFullScreenboolean在启动画面上隐藏状态栏。启动时使用 Android 12 API 则无效。仅适用于 Android。1.0.0
splashImmersiveboolean在启动画面上隐藏状态栏和软件导航按钮。启动时使用 Android 12 API 则无效。仅适用于 Android。1.0.0
layoutNamestring如果 useDialog 设置为 true，配置对话框布局。如果 useDialog 未设置或为 false，使用布局替代 ImageView。启动时使用 Android 12 API 则无效。仅适用于 Android。1.1.0
useDialogboolean使用 Dialog 替代 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>

显示启动画面

参数类型
options
ShowOptions

自从: 1.0.0

hide(...)​

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

隐藏启动画面

参数类型
options
HideOptions

自从: 1.0.0

接口​

ShowOptions​

属性类型描述默认值自从
autoHideboolean是否在 showDuration 后自动隐藏启动画面1.0.0
fadeInDurationnumber淡入持续时间（毫秒）。2001.0.0
fadeOutDurationnumber淡出持续时间（毫秒）。2001.0.0
showDurationnumber当 autoHide 启用时，启动画面显示的时间（毫秒）30001.0.0

HideOptions​

属性类型描述默认值自从
fadeOutDurationnumber淡出持续时间（毫秒）。在 Android 上，如果使用 Android 12 启动画面 API，则不使用此值。请改用 launchFadeOutDuration 配置选项。2001.0.0

Contents

编辑此页