cordova-plugin-splashscreen

Cordova 启动屏（Splash Screen）插件，用于在应用启动过程中显示预设图片，掩盖加载时的白屏或初始化状态，提升用户体验。支持自动 / 手动控制启动屏显示 / 隐藏，适配 Android、iOS 、OHOS等多平台多分辨率设备。本文重点说明OHOS的使用。

功能特性

• 🚀 启动时自动显示启动屏，无需额外代码

• ⏱️ 可配置自动隐藏延迟时间，默认web页面加载完毕后自动隐藏

• 🎮 支持 JavaScript API 手动控制显示 / 隐藏（适配复杂初始化场景）

• 📱 多平台适配：Android、iOS、OHOS 等 Cordova 支持的平台

• 📏 多分辨率兼容：为不同屏幕密度 / 尺寸配置专属启动屏图片

• 🔧 灵活配置：支持透明背景、淡入淡出效果

安装说明

1. 安装插件

通过 HCordova CLI 安装（支持 cordova-openharmony 2.0.0+）：

# 安装hcordova
npm install -g hcordova

# 安装最新版本
hcordova plugin add cordova-plugin-splashscreen

# 指定OHOS平台安装
hcordova plugin add cordova-plugin-splashscreen --platform ohos

# 从 GitCode 安装（获取最新开发版）
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-splashscreen.git --platform ohos

2. 卸载插件

hcordova plugin remove cordova-plugin-splashscreen

# 指定OHOS平台卸载
hcordova plugin remove cordova-plugin-splashscreen --platform ohos

核心配置（config.xml）

所有启动屏相关配置需在项目根目录的 config.xml 中声明，以下是完整配置示例：

基础全局配置

<!-- 在web加载完成后，自动隐藏 -->
<preference name="AutoHideSplashScreen" value="true" />

<!-- 必须在web加载完成后，延迟3秒钟关闭（0禁用闪屏） -->
<preference name="SplashScreenDelay" value="3000" />

<!-- 0禁用闪屏, 显示持续时间（在web初始化完后，显示的时间） -->
<preference name="SplashScreenDelay" value="1000"/>

<!-- 显示Spinner -->
<preference name="ShowSplashScreenSpinner" value="ture"/>

<!-- 全屏显示 -->
<preference name="SplashMaintainAspectRatio" value="ture"/>

<!-- 设置Spinner颜色 -->
<preference name="SplashScreenSpinnerColor" value="#ffffff"/>

<!-- 闪屏消失动画持续时间 -->
<preference name="FadeSplashScreenDuration" value="2000"/>

<!-- 闪屏全屏显示true:全屏，false：非全屏 -->
<preference name="SplashMaintainAspectRatio" value="true"/>

<!-- 闪屏关闭后全屏显示true:全屏，false：非全屏 -->
<preference name="FullScreenAfterCloseSplash" value="false" />

鸿蒙系统图片配置

资源图片名称竖屏：splash_portrait，横屏：splash_landscape，存放在在resource/media目录下，如果资源图片不存在，闪屏不启动或启动失败，无需在config.xml里面配置图片名称

JavaScript API 用法

如果需要手动控制启动屏（例如等待异步接口请求完成后隐藏），可使用以下 API：

1. 隐藏启动屏

// 基础用法：立即隐藏
navigator.splashscreen.hide();

// 配合延迟（例如等待 2 秒后隐藏）
setTimeout(() => {
    navigator.splashscreen.hide();
}, 2000);

2. 显示启动屏（应用运行中再次显示）

// 例如在页面跳转时显示加载屏
navigator.splashscreen.show();

注意事项

• 若设置 AutoHideSplashScreen="false"，web页面加载完毕自动隐藏，设置的时间无效，无需手动调用 hide()

• API 需在 deviceready 事件触发后调用（Cordova 插件通用规则）：

document.addEventListener("deviceready", () => {
    // 在这里调用 splashscreen API
    navigator.splashscreen.hide();
}, false);

常见问题（FAQ）

Q1: 启动屏不显示怎么办？

1. 检查插件是否安装成功：执行 hcordova plugin list 确认插件存在

2. 核实 config.xml 中参数是否正确（相对项目根目录）

3. 确保resources中各密度图片是否包含splash_portrait和splash_landscape图片

许可证

本插件基于 Apache License 2.0 开源，详情见 LICENSE 文件。

官方资源

• Apache Cordova（Android和iOS）：cordova-plugin-splashscreen 官方指南

• GitCode 仓库：OpenHarmony-Cordova/cordova-plugin-splashscreen