启动画面

此核心功能允许在您的 Web 应用程序启动时配置和控制平台的启动画面。

• 启动画面
  • 支持的平台
  • 平台启动画面图像配置
    • 示例配置
    • Android 特定信息
      • 示例 Android 配置
    • iOS 特定信息
      • 启动故事板图像
        • 设计启动故事板图像
        • 缩放
        • 语言环境
        • 尺寸类别
        • 单图像启动画面
        • 多图像启动画面
        • 深色模式
  • config.xml 偏好设置
    • AutoHideSplashScreen
    • FadeSplashScreen
    • FadeSplashScreenDuration
    • ShowSplashScreenSpinner
    • SplashScreenDelay
    • AndroidPostSplashScreenTheme
    • AndroidWindowSplashScreenAnimatedIcon
    • AndroidWindowSplashScreenAnimationDuration
    • AndroidWindowSplashScreenBackground
    • AndroidWindowSplashScreenBrandingImage
    • AndroidWindowSplashScreenIconBackgroundColor
  • JavaScript 公共 API
    • navigator.splashscreen.hide
    • navigator.splashscreen.show
  • 怪癖和已知问题
    • iOS
    • Android

支持的平台

• Android
• iOS

对于其他平台，请查看 cordova-plugin-splashscreen 以了解支持情况。

平台启动画面图像配置

示例配置

在顶层 config.xml 文件（不是 platforms 中的文件）中，添加此处指定的配置元素。

"src" 属性的值相对于项目根目录，而不是 www 目录（请参阅下面的 目录结构）。您可以随意命名源图像文件。应用程序中的内部名称由 Cordova 自动确定。

目录结构

projectRoot
    platforms
    plugins
    www
    res
        screen
            android
            ios

Config.xml

<platform name="android">
    <preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/splashscreen.xml" />
</platform>

<!--
  Storyboard (supports all devices):
  Note: images are determined by scale, idiom, and size traits. The following
  are suggested based on current device form factors
-->
<platform name="ios">
    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comcom.png" />
    <splash src="res/screen/ios/Default@3x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@3x~universal~anycom.png" />
    <splash src="res/screen/ios/Default@3x~universal~comany.png" />
</platform>

Android 特定信息

从 Android 12 开始，Google 实施了新的 SplashScreen API 来控制在 Android 12 及更高版本设备上运行的应用程序启动动画。为了向后兼容，Cordova 包含了 core-splashscreen 兼容库，将这些功能扩展到 Android API 21 及更高版本。

为了有效地创建您自己的 Android SplashScreen 资源，了解自适应图标的要求非常重要。

资源

• 启动画面尺寸
• 自适应图标

示例 Android 配置

<platform name="android">
    <!-- Default -->
    <preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/splashscreen.xml" />
</platform>

iOS 特定信息

启动故事板图像的大小基于缩放比例、语言环境和尺寸类别。它支持所有设备，并且可以与分屏/滑动多任务处理一起使用。

没有官方支持为 iPad Pro 12.9 提供原生分辨率启动图像，也没有支持提供适用于分屏多任务处理或滑动操作的启动图像。

注意：从 iOS 11 开始，对于 iPhone X 及更高版本（带刘海屏）的设备，请确保在 index.html 文件中的视口元标记中添加 viewport-fit=cover 以便正确显示应用程序，如下所示：<meta name="viewport" content="user-scalable=no, initial-scale=1, width=device-width, viewport-fit=cover">，并通过添加以下内容对您的应用程序样式进行一些修改：padding: env(safe-area-inset-top) 到您的 index.css 文件中，以避免屏幕中刘海后面的不安全区域。

启动故事板图像

为了支持更新的形状因素和分屏/滑动多任务处理，使用启动故事板图像。

• 图像不特定于给定设备。
• 图像将按比例缩放以填充可用的视口（同时保持纵横比）。
• 图像的外边缘将被裁剪，裁剪量将根据设备和视口而有所不同。
• 无需为每个可能的设备、视口和方向提供图像；iOS 将自动为当前情况选择最佳图像。

设计启动故事板图像

设计启动故事板图像的关键在于了解图像边缘几乎肯定会被裁剪。因此，不应将任何重要信息放置在提供的任何启动故事板图像的边缘附近。只有中心是安全区域，这几乎可以保证遵循 Apple 关于呈现未填充用户界面的建议不会很好地工作。

相反，以下提示应该使您能够创建一个适用于多种形状因素、视口和方向的启动图像

• 重要的图形（徽标、图标、标题）应居中。安全边界区域会有所不同，因此您需要进行测试以确保重要图形永远不会被裁剪。更好的是，一开始就不要提供任何重要的图形。

  • 您可以微调这些图形的放置和大小。

• 使用简单的颜色填充。如果您使用两种颜色，您将希望一种颜色填充图像的上半部分，另一种颜色填充下半部分。如果您使用渐变，您可能需要确保渐变的中间与图像的中心对齐。

• 不要担心像素完美 - 因为图像被缩放，图像几乎不可能完美地适应像素网格。由于所有支持的 iOS 设备都使用视网膜屏幕，因此用户很难注意到它。

为了有效地使用启动故事板图像，了解缩放比例、语言环境和尺寸类别特征的概念非常重要。在提供给启动故事板的图像中，iOS 将选择最符合设备和视口的图像并呈现该图像。如果需要，可以只提供一个启动图像，但也可以根据特征微调显示的启动图像。微调时，可以忽略应用程序未针对或不支持的特征。

缩放

一般来说，您需要提供 2x 和 3x 图像。Cordova 目前只支持视网膜设备，因此没有必要提供 1x 图像。

语言环境

除非您需要针对特定设备语言环境进行微调，否则您只需要提供通用图像。

尺寸类别

有两个尺寸类别适用于两个屏幕轴。窄视口被认为是“紧凑”尺寸类别，其余视口被认为是“常规”。但是，在向 Xcode 提供图像时，必须在“任何和紧凑”以及“任何和常规”之间进行选择。为了与原生术语保持一致，此功能将根据“任何”和“紧凑”进行匹配。any 将匹配常规大小的视口。

注意：此功能使用 com 作为“紧凑”类别的缩写。

此功能支持以下类别

单图像启动画面

如果您的启动图像很简单，您可能可以避免创建许多不同的启动图像，并且只提供一个。启动图像需要满足以下要求

• 图像应该是正方形的
• 图像应该足够大以适合 iPad Pro 12.9"：2732x2732
• 任何重要的内容都应该适合中心

请记住，图像将被裁剪，根据视口，可能会被严重裁剪。

创建图像后，您可以通过将以下内容添加到 config.xml 中来将其包含在您的项目中

    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />

由于只提供了一个图像，因此 iOS 将在所有上下文中使用它。

多图像启动画面

如果单个启动图像无法满足您的需求，您可能需要提供至少六个图像，甚至更多。此外，请记住，将无法将图像微调到特定设备，而只能微调到设备类别、显示因子和视口大小。

如果您不需要将图像定位到特定语言环境，则应创建六个图像，如下所示

* 此图像是必需的，以便 iOS 在此缩放比例和语言环境中使用其他图像。

注意：如果 3x 大小看起来太小，那是因为目前只有一个设备类别具有 3x 密度：iPhone 6+/6s+/7+。

以上内容在 config.xml 中看起来像以下代码片段

    <splash src="res/screen/ios/Default@2x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comany.png" />
    <splash src="res/screen/ios/Default@2x~universal~comcom.png" />
    <splash src="res/screen/ios/Default@3x~universal~anyany.png" />
    <splash src="res/screen/ios/Default@3x~universal~anycom.png" />
    <splash src="res/screen/ios/Default@3x~universal~comany.png" />

如果需要根据设备语言环境进一步微调，可以这样做。这可能看起来像这样

* 此图像是必需的，以便 iOS 在此缩放比例和语言环境中使用其他图像。

以上内容在 config.xml 中看起来像这样

    <splash src="res/screen/ios/Default@2x~iphone~anyany.png" />
    <splash src="res/screen/ios/Default@2x~iphone~comany.png" />
    <splash src="res/screen/ios/Default@2x~iphone~comcom.png" />
    <splash src="res/screen/ios/Default@3x~iphone~anyany.png" />
    <splash src="res/screen/ios/Default@3x~iphone~anycom.png" />
    <splash src="res/screen/ios/Default@3x~iphone~comany.png" />
    <splash src="res/screen/ios/Default@2x~ipad~anyany.png" />
    <splash src="res/screen/ios/Default@2x~ipad~comany.png" />

深色模式

从 [email protected] 开始，现在可以选择指定不同的 SplashScreen 图像以在应用程序以深色模式运行时使用。SplashScreen 图像的亮度可以在 config.xml 中使用 ~dark 和 ~light 后缀定义。

<!-- Default image to be used for all modes -->
<splash src="res/screen/ios/Default@2x~universal~anyany.png" />

<!-- Image to use specifically for dark mode devices -->
<splash src="res/screen/ios/Default@2x~universal~anyany~dark.png" />

<!-- Image to use specifically for light mode devices -->
<splash src="res/screen/ios/Default@2x~universal~anyany~light.png" />

注意：此功能从 iOS 13 开始有效。iOS 12 及更低版本将使用默认的 SplashScreen，而不会指定亮度后缀。

config.xml 偏好设置

AutoHideSplashScreen

指示是否自动隐藏启动画面。启动画面将在 SplashScreenDelay 偏好设置中指定的时间量后隐藏。

支持的平台

• Android
• iOS

数据类型：布尔值

默认值：true

使用示例

<preference name="AutoHideSplashScreen" value="true" />

FadeSplashScreen

控制启动画面淡入淡出的效果。

对于 Android，它只控制淡出效果。

支持的平台

• Android
• iOS

数据类型：布尔值

默认值：true

使用示例

<preference name="FadeSplashScreen" value="false"/>

FadeSplashScreenDuration

控制启动画面淡出效果的持续时间。

支持的平台

• Android
• iOS

数据类型：Float，以毫秒为单位

默认值：500

使用示例

<preference name="FadeSplashScreenDuration" value="750"/>

iOS 注意：FadeSplashScreenDuration 包含在 SplashScreenDelay 中，例如，如果您在 config.xml 中定义了 <preference name="SplashScreenDelay" value="3000" /> 和 <preference name="FadeSplashScreenDuration" value="1000"/>

• 00:00 - 显示启动画面
• 00:02 - 淡出开始
• 00:03 - 启动画面隐藏

通过 <preference name="FadeSplashScreen" value="false"/> 关闭淡出效果，实际上意味着淡出持续时间为 0，因此在本例中，启动画面的总延迟时间仍然为 3 秒。

注意：这仅适用于应用程序启动 - 您需要在应用程序代码中手动显示/隐藏启动画面时考虑淡出超时时间。

navigator.splashscreen.show();
window.setTimeout(function () {
    navigator.splashscreen.hide();
}, splashDuration - fadeDuration);

ShowSplashScreenSpinner

控制启动画面加载动画。

支持的平台

• iOS

数据类型：布尔值

默认值：true

使用示例

<preference name="ShowSplashScreenSpinner" value="false"/>

SplashScreenDelay

自动隐藏启动画面之前等待的时间（以毫秒为单位）。

支持的平台

• Android
• iOS

数据类型：Number，以毫秒为单位

默认值：true

• Android -1：启动画面将在触发 onPageFinished 事件后自动隐藏。

• iOS 3000：启动画面将在 3 秒后自动隐藏。

使用示例

<preference name="SplashScreenDelay" value="3000" />

AndroidPostSplashScreenTheme

设置启动画面隐藏后活动的主题。

注意：此设置可用，但使用风险自负。

支持的平台

• Android

数据类型：String

默认值：@style/Theme.AppCompat.NoActionBar

使用示例

<preference name="AndroidPostSplashScreenTheme" value="@style/Theme.AppCompat.NoActionBar"/>

AndroidWindowSplashScreenAnimatedIcon

启动画面图像。此首选项用于动画和非动画图标。当前可接受的资产文件可以是 XML 矢量可绘制对象或 PNG。

:warning: 使用 自适应图标 需要将最小 SDK 设置为 26。

:warning: 一些 XML 矢量 功能 需要将最小 SDK 设置为 24。

支持的平台

• Android

数据类型：String，资产文件的路径

默认值：如果没有提供，则使用 Cordova 的默认资产。

使用示例

<preference name="AndroidWindowSplashScreenAnimatedIcon" value="res/screen/android/splashscreen.xml" />

AndroidWindowSplashScreenAnimationDuration

定义如果提供动画矢量可绘制对象作为启动画面图像，则图标动画的持续时间。

支持的平台

• Android

数据类型：Number，以毫秒为单位

默认值：undefined

使用示例

<preference name="AndroidWindowSplashScreenAnimationDuration" value="3000"/>

AndroidWindowSplashScreenBackground

启动画面背景颜色。

支持的平台

• Android

数据类型：String，颜色十六进制代码值。

默认值：#ffffff

使用示例

<preference name="AndroidWindowSplashScreenBackground" value="#ffffff" />

AndroidWindowSplashScreenBrandingImage

:warning: 此设置当前不受支持。Cordova Android 依赖的用于提供向后兼容性的核心启动画面兼容库尚未实现此功能。 查看 Google Android 问题跟踪器

AndroidWindowSplashScreenIconBackgroundColor

启动画面图标的背景颜色。有助于区分背景和图标之间的对比度。

支持的平台

• Android

数据类型：String，颜色十六进制代码值。

默认值：undefined

使用示例

<preference name="AndroidWindowSplashScreenIconBackgroundColor" value="#c0c0c0" />

JavaScript 公共 API

navigator.splashscreen.hide

关闭启动画面。

支持的平台

• Android
• iOS

使用示例

navigator.splashscreen.hide();

iOS 特性

config.xml 文件的 AutoHideSplashScreen 设置必须为 false。要延迟隐藏启动画面两秒钟，请在 deviceready 事件处理程序中添加一个计时器，例如以下内容

setTimeout(function() {
    navigator.splashscreen.hide();
}, 2000);

navigator.splashscreen.show

显示启动画面。

支持的平台

• iOS

使用示例

navigator.splashscreen.show();

您的应用程序在应用程序启动并触发 deviceready 事件之前无法调用 navigator.splashscreen.show()。但由于启动画面通常在应用程序启动之前可见，这似乎会违背启动画面的目的。在 config.xml 中提供任何参数将自动在应用程序启动后立即显示启动画面，并在应用程序完全启动并收到 deviceready 事件之前。因此，您不太可能需要调用 navigator.splashscreen.show() 来使启动画面在应用程序启动时可见。

怪癖和已知问题

iOS

1. 在 iOS 中，启动画面图像称为启动图像。这些图像在 iOS 上是必需的。

2. 目标应用程序可能不会反映图像的更改 在目标应用程序上运行应用程序后，iOS 会缓存启动图像。不幸的是，当您更改图像时，iOS 不会使缓存失效，这意味着您仍然会看到旧的启动图像。您应该：删除应用程序，或重置内容和设置（模拟器）。

3. 从 CLI 启动时，模拟器可能不会显示预期的图像 当 Xcode 部署到特定模拟器时，它只复制与模拟器特征匹配的资产。例如，如果您尝试在 iPhone 6s Plus 模拟器上运行应用程序，则只复制 @3x 启动图像。但是，从 CLI 编译时，默认情况下会假设 iPhone 5s，这意味着只复制 @2x 启动图像。除非您的启动图像有明显不同，否则很可能不会注意到差异，但这确实意味着测试的唯一准确方法是在物理设备上进行测试。

4. 必须提供 anyany 以使用其他变体 如果您没有为特定比例和 idiom 提供启动图像的 anyany 版本，则其他变体（如 anycom、comany 和 comcom）将被忽略。

Android

1. Android 12 在从 Android Studio 或 Cordova CLI 启动应用程序时不会显示启动画面。 这是一个已知的 Android 12 问题。将应用程序上传到设备或模拟器后，退出并打开应用程序将显示启动画面。如果更改未显示，请尝试执行干净构建。此问题已在 Android 13 上修复。