@capacitor/splash-screen

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/splash-screen是capacitor生态系统中的核心插件，用于显示或隐藏启动画页面，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档只说明在OpenHarmony系统中的使用。

应用启动时，会加载OpenHarmony原生启动页配置，进行启动样式展示，建议使用原生默认配置 启动。

API可实现启动画页面的显示或隐藏操作，适配OpenHarmony系统的启动页展示需求。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

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

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/splash-screen

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/splash-screen",
  "classpath": "SplashScreen"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(SplashScreen)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  SplashScreen
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将插件源码中src/main/cpp/Splashscreen目录下的Splashscreen.h、Splashscreen.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Splashscreen目录下

卸载

# 卸载 splash-screen 插件
hionic plugin remove @capacitor/splash-screen

约束与限制

兼容性

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

1. capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

资源图片配置

资源图片名称为 androidSplashResourceName，需存放在 resource/media 目录下；若资源图片不存在，启动屏将显示设置的背景颜色或启动失败，需在 capacitor.config.json 中配置该图片名称。

配置

以下为插件支持的配置项，可在 capacitor.config.json 中进行配置，适配启动屏展示效果：

| 配置项 | 类型 | 描述 | |---------------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------| | launchShowDuration | number | 当自动隐藏启用时，启动画面显示的时长（单位：毫秒） | | launchAutoHide | boolean | 应用启动后，启动画面是否自动隐藏 | | launchFadeOutDuration | number | 启动画面淡出动画的时长（单位：毫秒） | | backgroundColor | string | 启动画面背景颜色（十六进制格式），支持 #RRGGBB 或 #RRGGBBAA | | androidSplashResourceName | string | 作为启动画面的资源图片名称，需存放在 resource/media 目录下 | | androidScaleType | 'CENTER' | 'CENTER_CROP' | 'CENTER_INSIDE' | 'FIT_CENTER' | 'FIT_END' | 'FIT_START' | 'FIT_XY' | 启动画面图片的缩放方式 | | showSpinner | boolean | 是否在启动画面上显示加载旋转器 | | androidSpinnerStyle | 'horizontal' | 'small' | 'large' | 'inverse' | 'smallInverse' | 'largeInverse' | Android平台上旋转器的样式 | | iosSpinnerStyle | 'small'| 'large' | iOS平台上旋转器的样式（本文档仅说明OpenHarmony使用，供参考） | | spinnerColor | string | 旋转器颜色（十六进制格式），支持 #RRGGBB 或 #RRGGBBAA | | splashFullScreen | boolean | 是否隐藏启动画面上的状态栏 | | splashImmersive | boolean | 是否隐藏启动画面上的状态栏和软件导航按钮 | | layoutName | string | 暂不支持 | | useDialog | boolean | 暂不支持 |

配置示例

配置文件路径：capacitor.config.json

{
  "plugins": {
    "SplashScreen": {
      "launchShowDuration": 2000,
      "launchAutoHide": true,
      "launchFadeOutDuration": 200,
      "backgroundColor": "#ffffffff",
      "androidSplashResourceName": "splash",
      "androidScaleType": "CENTER",
      "showSpinner": true,
      "androidSpinnerStyle": "large",
      "iosSpinnerStyle": "large",
      "spinnerColor": "#f1a71dff",
      "splashFullScreen": true,
      "splashImmersive": true
    }
  }
}

使用示例

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

import { SplashScreen } from '@capacitor/splash-screen';

// 隐藏启动屏（建议在应用启动时执行）
await SplashScreen.hide();

// 显示启动屏，无限期显示（不自动隐藏）
await SplashScreen.show({
  autoHide: false,
});

// 显示启动屏，持续2秒后自动隐藏
await SplashScreen.show({
  showDuration: 2000,
  autoHide: true,
});

使用说明

SplashScreen是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用，适用于应用启动时的启动屏控制场景。

核心 API

接口方法

| 方法名 | 请求参数 | 返回类型 | 描述 | |-----------|----------------------------------------------------|---------------------|---------| | show(...) | options?: ShowOptions | undefined | Promise<void> | 显示启动画页面 | | hide(...) | options?: HideOptions | undefined | Promise<void> | 隐藏启动画页面 |

数据结构

ShowOptions

调用 show 方法时的入参对象，用于配置启动屏显示相关参数。

| 数据 | 类型 | 描述 | |-----------------|---------|-----------------------| | autoHide | boolean | 启动屏显示后是否自动隐藏 | | fadeInDuration | number | 启动屏淡入时间（单位：毫秒） | | fadeOutDuration | number | 启动屏淡出时间（单位：毫秒） | | showDuration | number | 启动屏从显示到开始隐藏的时间（单位：毫秒） |

HideOptions

调用 hide 方法时的入参对象，用于配置启动屏隐藏相关参数。

| 数据 | 类型 | 描述 | |-----------------|--------|----------------| | fadeOutDuration | number | 启动屏淡出时间（单位：毫秒） |

目录结构

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

贡献代码

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

许可证

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