跳到主要内容
版本：v6

@capacitor/splash-screen

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

安装​

npm install @capacitor/splash-screen
npx cap sync

Android 12 启动画面 API​

这仅影响启动时的启动画面，在使用编程方式 show() 方法时不使用。

Capacitor 4 使用 Android 12 Splash Screen API 和 androidx.core:core-splashscreen 兼容库，使其在 Android 11 及以下版本上也能工作。

可以通过将 AppTheme.NoActionBarLaunch 的父主题从 Theme.SplashScreen 更改为 AppTheme.NoActionBar（在 android/app/src/main/res/values/styles.xml 中）来禁用兼容库。Android 12 Splash Screen 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';

// 隐藏启动画面（应在应用启动时执行）
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 Splash Screen 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.2.0）

示例指南​

添加您自己的图标和启动画面图像 ›

为 Capacitor（Android）创建动态/自适应启动画面 ›

API 参考​

show(...)​

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

显示启动画面。

ParamType
optionsShowOptions

自版本： 1.0.0

hide(...)​

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

隐藏启动画面。

ParamType
optionsHideOptions

自版本： 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 Splash Screen API，则不使用此值。请改用 launchFadeOutDuration 配置选项。2001.0.0

目录

编辑此页