npm package: @luqi_test/cordova-plugin-splashscreen
Description: Cordova Splashscreen Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 6.0.2

# 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+）：


```bash
# 安装hcordova
npm install -g hcordova
```


```bash
# 安装最新版本
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. 卸载插件

```bash
hcordova plugin remove cordova-plugin-splashscreen

# 指定OHOS平台卸载
hcordova plugin remove cordova-plugin-splashscreen --platform ohos
```

## 核心配置（config.xml）

所有启动屏相关配置需在项目根目录的 `config.xml` 中声明，以下是完整配置示例：

### 基础全局配置



```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. 隐藏启动屏

```js
// 基础用法：立即隐藏
navigator.splashscreen.hide();

// 配合延迟（例如等待 2 秒后隐藏）
setTimeout(() => {
    navigator.splashscreen.hide();
}, 2000);
```

### 2. 显示启动屏（应用运行中再次显示）



```js
// 例如在页面跳转时显示加载屏
navigator.splashscreen.show();
```

### 注意事项



* 若设置 `AutoHideSplashScreen="false"`，**web页面加载完毕自动隐藏，设置的时间无效，无需手动调用&#x20;**`hide()`

* API 需在 `deviceready` 事件触发后调用（Cordova 插件通用规则）：



```js
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) 开源，详情见 LICENSE 文件。

## 官方资源

* Apache Cordova（Android和iOS）：[cordova-plugin-splashscreen 官方指南](https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-splashscreen/)

* GitCode 仓库：[OpenHarmony-Cordova/cordova-plugin-splashscreen](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-splashscreen)