跳至主要内容
版本：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 及更低版本上运行。

可以通过将 AppTheme.NoActionBarLaunch 的父级从 Theme.SplashScreen 更改为 AppTheme.NoActionBar 在 android/app/src/main/res/values/styles.xml 中禁用兼容库。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 问题追踪器** **Google 问题追踪器** 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 具有以下选项

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

对于 iOS，iosSpinnerStyle 具有以下选项

  • large（默认）
  • small

要设置旋转器的颜色，请使用 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）

示例指南​

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

为电容 (Android) 创建动态/自适应启动画面 ›

API​

show(...)​

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

显示启动画面

参数类型
optionsShowOptions

自 1.0.0

hide(...)​

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

隐藏启动画面

参数类型
optionsHideOptions

自 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

内容

编辑此页面