启动画面

此核心功能允许您在 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 启动画面资源，理解自适应图标的要求非常重要。

资源

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

Android 配置示例

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

iOS 特定信息

启动故事板图像根据缩放、习语和尺寸类进行调整大小。它支持所有设备，并且可以与分屏/滑动覆盖多任务处理一起使用。

没有官方支持为 iPad Pro 12.9 提供原生分辨率的启动图像，也没有支持提供与分屏多任务处理或滑动覆盖一起使用的启动图像。

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

启动故事板图像

为了支持更新的外形尺寸和分屏/滑动覆盖多任务处理，将使用启动故事板图像。

• 图像并非特定于给定设备。
• 图像会缩放以填充可用的视口（同时保持纵横比）。
• 图像的外边缘将被裁剪，裁剪量将根据设备和视口而变化。
• 无需为每个可能的设备、视口和方向提供图像；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] 以来，现在可以选择指定在应用以深色模式运行时使用的不同启动画面图像。可以使用 ~dark 和 ~light 后缀在 config.xml 中定义启动画面图像的亮度。

<!-- 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 及更低版本将使用未指定亮度后缀的默认启动画面。

config.xml 首选项

AutoHideSplashScreen

指示是否自动隐藏启动画面。启动画面会在 SplashScreenDelay 首选项中指定的时间过后隐藏。

支持的平台

• Android
• iOS

数据类型： Boolean

默认值： true

用法示例

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

FadeSplashScreen

控制启动画面淡入和淡出的能力。

对于 Android，它仅控制淡出。

支持的平台

• Android
• iOS

数据类型： Boolean

默认值： 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

数据类型： Boolean

默认值： true

用法示例

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

SplashScreenDelay

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

支持的平台

• Android
• iOS

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

默认值： true

• Android -1：当 onPageFinished 事件被触发时，启动画面将自动隐藏。

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

用法示例

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

AndroidPostSplashScreenTheme

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

注意： 此设置可用，但请自行承担风险。

支持的平台

• 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 事件之前自动 show 显示启动画面。 因此，您不太可能需要调用 navigator.splashscreen.show() 来使启动画面在应用程序启动时可见。

怪癖 & 已知问题

iOS

1. 在 iOS 中，启动画面图像被称为启动图像。 这些图像在 iOS 上是强制性的。

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

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

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

Android

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