跳到主要内容
版本：v5

@capacitor/splash-screen

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

安装​

npm install @capacitor/splash-screen@latest-5
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 问题追踪器 Google 问题追踪器 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当启用 launchAutoHide 时，启动闪屏的显示时长（单位：毫秒）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是否在闪屏上显示加载指示器（spinner）。当 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.0）

示例指南​

添加自定义图标和启动画面图片 ›

为 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

编辑此页