uni-app启动界面(splash)参数配置说明

2023年12月5日发(作者：姆巴佩与梅西关系紧张)

uni-app启动界面（splash）参数配置说明

说明：应用启动时为了提升用户体验（不显示黑屏）需设置启动界面，相关配置参考文件中的“应用图标和启动图片”章节。

启动界面的默认逻辑是应用启动时显示，此时在后台异步加载应用的入口页面（通常为），当入口页面加载完

成后（webview的loaded事件触发）自动关闭启动界面并显示入口页面。即App引擎会自动检测首页渲染，若未渲染则

不关闭splash，提升用户体验。

1. 启动图配置项（ —> app-plus —>

splashscreen）

属性

alwaysShowBeforeRen

der

waiting

类型

Boolea

n

Boolea

n

Boolea

n

Boolea

n

默认

值

true

描述备注

白屏时是否

开启

程序启动界面

为保证用户体验，建议开启

true

程序启动界面是否

显示

等待雪花

-

autoclosetrue

App引擎是否

自动关闭

程序启动界面

启动界面在应用的首页面加载完毕后

延迟关

闭的时间

-

仅在 autoclose 设置为 true 时

有效

delay0

(1) alwaysShowBeforeRender 可设置首页白屏检测开关，默认为true，则splash的关闭逻辑为：

App启动时，App引擎自动检测首页渲染情况，若首页未渲染（白屏），则不关闭splash；否则，关闭splash；

若启动时间超过10秒，则不管首页是否白屏，自动关闭splash

注意：若App启动时有动态显示其他页面的需求，场景举例：

欢迎页场景：首次启动，显示App欢迎页；否则，显示首页内容

登录页场景：用户未登录，打开登录页；否则，显示首页内容

此时，App引擎无法高效判断首页及跳转页渲染情况，建议将alwaysShowBeforeRender 设置为false，开发者手动

调用 plashscreen() 关闭启动界面。

(2) autoclose

默认为true：此时delay设置有效（delay 不能任意使用，从应用启动到 splash 关闭的总时长，不会超过 6s。也就是说，delay 的时长也是

计算在这个 6s 的限制内）。

修改为false：需开发者手动调用 plashscreen() 方法关闭启动图（这个时间不能太晚，6s 超时后依旧会主动关

闭）；通常在打开入口页面时还需要做一些额外的业务逻辑等待操作（如提交服务器更新数据，预创建Webview窗口等）时使用。

2. 示例

\"splashscreen\" : {

\"alwaysShowBeforeRender\" : true,//白屏时是否开启程序启动界面

\"waiting\" : true,//程序启动界面是否显示等待雪花

\"autoclose\" : true,//是否自动关闭程序启动界面

\"delay\" : 0 //启动界面在应用的首页面加载完毕后延迟关闭的时间

},

3. 常见启动界面问题

(1) 应用一直停留在启动界面无法进入应用

查看中plus->splashscreen节点下的autoclose属性值，如果设置为false则需要查看应用的入口页面()中是否正确调

用plashscreen()方法

通常如果不需要做一些业务逻辑等待（如等待服务器返回数据、预创建Webview窗口等）操作的情况，应该直接将autoclose属性值设置true

HBuilder新建的空白App默认是自动关闭启动画面的，但官方的几个示例，如Hello H5+、Hello mui的启动图片都是在

首页的plusready里手动关闭的。如果开发者新建了示例模板应用，又删除了首页plusready里的

plashscreen()，就会导致应用停留在启动界面无法进入。

切记不要在页面初始时使用alert()

如果你在plus ready里调用了plashscreen()，但是在该代码生效前使用了alert，那么由于alert阻断了后续代码的执

行，根本无法执行到closeSplashscreen，进而导致启动封面关不掉。

(2) 是否可自定义html页面作为应用启动界面

App云端打包不支持，如果有原生开发环境，则可以使用5+ SDK做原生开发来实现。

参考：uni-app 启动界面（splash）参数配置说明 | 启动慢的原因 和 启动界面、封面图片、Splash关不掉，一直转圈，无法进入