@ionic-native/splash-screen

本项目基于@ionic-native/[email protected]开发。

简介

一个用于显示或隐藏启动画面的插件，支持在应用启动时显示启动画面，并在适当的时候隐藏。兼容Android、iOS和OpenHarmony平台，为跨平台应用开发提供统一的启动屏管理能力。本文档主要说明在OpenHarmony系统中的应用。

在移动应用开发中，启动画面是提升用户体验的重要组成部分。@ionic-native/splash-screen插件通过封装原生平台API，为开发者提供了统一的跨平台接口，无需深入原生开发即可实现启动屏的显示和隐藏功能。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @ionic-native/splash-screen

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @ionic-native/splash-screen

手动引入安装

1.添加插件配置

根据plugin.xml的config-json项，找到entry模块中config.xml文件，并根据param标签添加配置

<feature name="SplashScreen">
  <param name="harmony-package" value="SplashScreen" />
  <param name="onload" value="true" />
</feature>

2.修改CMake配置

根据plugin.xml的CMakeLists项，找到cordova模块，路径为target字段的文件CMakeLists.txt，添加add_library

add_library(cordova SHARED
  // ...
  SplashScreen/SplashScreen.cpp
  // ...
)

3.复制源码文件

根据plugin.xml的source-file项，将src字段的路径代码复制到cordova模块中target-dir字段的目录中：

将源码中src/main/cpp/SplashScreen目录下的SplashScreen.h、SplashScreen.cpp文件引入到cordova模块中src/main/cpp/SplashScreen目录下。

将源码中src/main/ets/components/SplashScreen目录下的SplashScreen.ets文件引入到cordova模块中src/main/ets/components/SplashScreen目录下。

4.添加ArkTS配置

在cordova模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤3中拷贝的ets文件路径:

"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/SplashScreen/SplashScreen.ets"
        // ...
      ]
    }
  }
}

卸载

# hionic CLI卸载
hionic plugin remove @ionic-native/splash-screen

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不涉及

使用示例

示例1：显示和隐藏启动屏

实现显示和隐藏启动画面的功能。

import { SplashScreen } from "@ionic-native/splash-screen";

// 显示启动屏
SplashScreen.show();
console.log('启动屏已显示');

// 隐藏启动屏
SplashScreen.hide();
console.log('启动屏已隐藏');

使用说明

插件在全局对象 SplashScreen 下暴露所有功能接口，使用前需确保设备就绪事件（deviceready）已触发。

1. 显示启动屏

显示应用的启动画面。

方法签名

SplashScreen.show()

2. 隐藏启动屏

隐藏应用的启动画面。

方法签名

SplashScreen.hide()

配置说明

以下配置值可用:

| 数据 | 类型 | 描述 | | ---- | ---- | ---- | | AutoHideSplashScreen | string | 当自动隐藏（以毫秒计）启用时，启动启动画面显示多长时间 | | SplashScreenDelay | string | 显示持续时间 | | ShowSplashScreenSpinner | string | 显示Spinner | | SplashMaintainAspectRatio | string | 全屏显示 | | SplashScreenSpinnerColor | string | Spinner颜色 | | FadeSplashScreenDuration | string | 闪屏消失动画持续时间 | | FullScreenAfterCloseSplash | string | 闪屏关闭后是否全屏显示 |

示例

核心配置（config.xml）

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

载于：config.xml

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

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

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

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

<!-- 设置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里面配置图片名称。

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |---- cpp  # C++ 代码
|           |---- ets  # ArkTS 代码
|     |---- www    # Web 侧代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提Issue，当然，也非常欢迎发PR共建。

许可证

本插件基于MIT License开源，详见LICENSE文件。