WebToApp 启动闪屏Splash配置指南从图片/视频选择、倒计时与跳过逻辑到 APK 打包加密本篇指南讲解 WebToApp 项目中「编辑通用配置Edit Common Config」里的Splash Screen启动闪屏功能如何在应用启动时展示一张图片或一段视频并精细控制展示时长、点击跳过、倒计时、横竖屏方向、裁剪适配、视频音频与裁剪区间以及这些配置如何被打包进导出的 APK含可选加密。读完本文你将掌握闪屏功能在编辑器中的全部选项、底层配置字段splashEnabled/splashConfig与运行期实现原理并能在自己的应用上直接复现配置。功能入口与整体概念闪屏是应用启动瞬间展示给用户的第一屏常用于品牌露出、过渡缓冲或承载激活/公告流程。在 WebToApp 中该功能位于编辑通用配置Edit Common Config编辑器内的Splash screen启动闪屏卡片中相关文档见 splash.md。从数据模型看每个应用WebApp通过两个字段控制闪屏见 WebApp.ktval splashEnabled: Boolean false, val splashConfig: SplashConfig? null,splashEnabled闪屏总开关splashConfig完整的闪屏行为配置为null时视为未启用。对应的SplashConfig定义在 WebApp.ktdata class SplashConfig( val type: SplashType SplashType.IMAGE, // IMAGE / VIDEO val mediaPath: String? null, // 闪屏媒体文件路径 val duration: Int 3, // 展示时长秒图片闪屏使用 val clickToSkip: Boolean true, // 是否允许点击跳过 val orientation: SplashOrientation SplashOrientation.PORTRAIT, val fillScreen: Boolean true, // 裁剪填充 vs 完整适配 val enableAudio: Boolean false, // 视频闪屏是否播放声音 val videoStartMs: Long 0, // 视频裁剪起点毫秒 val videoEndMs: Long 5000, // 视频裁剪终点毫秒 val videoDurationMs: Long 0, // 视频总时长毫秒编辑器裁剪用 val showCountdown: Boolean true // 是否显示剩余秒数倒计时 )配套枚举SplashTypeIMAGE/VIDEO与SplashOrientationPORTRAIT/LANDSCAPE也定义在同一文件中。编辑器选项逐项说明编辑器卡片实现在 CreateAppSplashCard.kt对应文档中的全部选项如下选项对应配置字段说明Enable启用splashEnabled闪屏总开关。关闭时整张卡片折叠相关配置保留但不再生效。Media媒体splashConfig.mediaPath/type选择图片image/*或视频video/*。卡片提供「选择图片」「选择视频」两个按钮选中后展示预览图片显示缩略图视频显示裁剪控件。Duration时长splashConfig.duration图片闪屏的展示秒数编辑器滑块范围为15 秒valueRange 1f..5f默认 3。Click to skip点击跳过splashConfig.clickToSkip允许用户点击屏幕直接跳过闪屏。Show countdown显示倒计时splashConfig.showCountdown独立控制在闪屏右上角显示剩余秒数与点击跳过互不影响。Orientation方向splashConfig.orientation切换横屏LANDSCAPE或竖屏PORTRAIT展示闪屏。Fill screen铺满屏幕splashConfig.fillScreentrue时按裁剪Crop铺满全屏false时按完整适配Fit显示。Enable audio启用音频splashConfig.enableAudio仅视频闪屏可见控制视频是否带声音播放默认静音。Video trim视频裁剪splashConfig.videoStartMs/videoEndMs为视频闪屏设置起止裁剪区间毫秒。编辑器内置VideoTrimmer控件并记录videoDurationMs供滑块参考。Clear media清除媒体—移除已选闪屏媒体回到选择态。几个值得注意的交互细节均可从 CreateAppSplashCard.kt 验证卡片会校验媒体文件是否存在checkMediaExists若所选 URI 对应的文件已被删除会自动触发onClearMedia清空选择「显示时长」「启用音频」等选项仅在对应媒体类型下显示图片类型不显示时长以外的视频选项视频类型不显示时长滑块「横屏显示」开关本质是把orientation在LANDSCAPE与PORTRAIT之间切换。媒体选择后的落盘处理媒体并不直接引用系统相册 URI而是先复制进应用私有目录。相关实现见 SplashStorage.kt视频以splash_uuid.mp4命名通过openInputStream 缓冲拷贝保存图片先按MAX_IMAGE_SIZE 1920计算采样比例calculateInSampleSize超限时等比缩放最终以 PNG 格式保存支持的扩展名视频mp4 / webm / 3gp / mkv / avi / mov图片png / jpg / jpeg / gif / webp / bmp文件统一存放在filesDir/splash_media/目录并提供deleteMedia、cleanupUnusedMedia、getStorageStats等管理接口。闪屏在导出 APK 中的运行流程导出阶段打包与可选加密导出 APK 时闪屏媒体会被嵌入应用资源。核心逻辑在 ApkBuilder.kt 的addSplashMediaToAssets媒体以固定资源名写入 APK图片为assets/splash_media.png视频为assets/splash_media.mp4若启用资源加密encryptionConfig.enabled则写入assets/splash_media.ext.enc加密文件超过10 MB的视频走专门的流式处理分支加密模式下用encryptLargeFile非加密模式下用writeEntryStoredStreaming避免一次性读入内存写入前会校验文件存在、可读且非空否则跳过并记录日志。导出配置块由buildSplashBlock()生成ApkBuilder.kt将splashEnabled、type、duration、clickToSkip、videoStartMs、videoEndMs、landscape、fillScreen、enableAudio、showCountdown全部序列化进 APK 的配置 JSON。辅助函数getSplashMediaPath()ApkBuilder.kt保证只有splashEnabled true时才返回媒体路径。运行阶段导出应用的启动闪屏导出后的应用通过 SplashLauncherActivity.kt 承载启动闪屏其关键行为通过AppModifyPayload接收闪屏配置仅当splashEnabled、mediaPath非空且文件真实存在时展示闪屏否则直接拉起目标页若orientation LANDSCAPE在onCreate中强制SCREEN_ORIENTATION_LANDSCAPE图片闪屏LaunchedEffect(countdown)每秒递减倒数到 0 后结束闪屏并启动目标 Activity点击跳过clickToSkip会立即结束视频闪屏使用MediaPlayerSurfaceView播放seekTo(videoStartMs)后播放到videoEndMs暂停并结束音频按enableAudio设置音量 1f 或 0f代码对「返回键打断播放」「播放器已释放」等竞态做了防御注释引用 issue #612倒计时芯片视频模式显示剩余毫秒向上取整的秒数图片模式显示countdown数值同时展示可选的「Skip」文字整个芯片固定在右上角Alignment.TopEnd。此外在 WebToApp 自身的 WebView 壳/预览场景中同样有一套 Compose 覆盖层 WebViewSplashOverlay.kt行为与导出版一致fillScreen直接映射为ContentScale.Crop裁剪铺满或ContentScale.Fit完整适配背景固定为黑色Color.Black视频循环关闭isLooping false播放到videoEndMs后回调onComplete芯片使用statusBarsPadding()这正是文档 Notes 中「状态栏可见时倒计时/跳过芯片自动位于状态栏下方纯全屏时停留在顶部角落」的实现来源。启动流程中的优先级激活 → 公告 → 闪屏值得说明的是闪屏并非导出应用启动流程的唯一环节。从 SplashLauncherActivity.kt 可以确认启动顺序若启用激活activationEnabled先做本地/远程激活校验未激活时弹出激活对话框若启用公告announcementEnabled且满足展示条件先弹公告关闭后再进入闪屏最后才展示闪屏结束后拉起目标 ActivityonLaunchTarget。理解这一顺序有助于排查「闪屏不出现」的问题它可能只是被激活或公告流程挡在了前面。数据落库与测试佐证WebApp是 Room 实体表web_appssplashConfig等嵌套配置通过 Converters.kt 序列化存储因此闪屏配置随应用数据持久化。在测试侧EditStateMapperTest.kt 验证了SplashConfig(type SplashType.IMAGE, mediaPath file:///splash.png)能被正确映射为编辑态的splashMediaUri即「编辑器选择媒体 → 编辑态 URI → 落盘路径」这条链路是有测试保障的。小结与实用建议综合以上内容可以提炼出几条直接可用的实操建议图片闪屏设置 15 秒时长默认 3 秒打开「点击跳过」避免用户等待过长「显示倒计时」可与跳过并存右上角会呈现Ns | Skip芯片。视频闪屏通过「视频裁剪」把展示片段限定在videoStartMsvideoEndMs默认整段取前 5 秒超 10 MB 的视频在导出时会走流式写入加密开启后仍受支持默认静音需要配音时打开「启用音频」。适配与方向fillScreen true时媒体按 Crop 裁剪铺满、无黑边但有裁切风险false时完整显示但可能留黑边。横屏应用记得把闪屏方向同步设为LANDSCAPE。打包验证导出后可在 APK 的assets/下看到splash_media.png或splash_media.mp4开启资源加密时为.enc文件这是确认闪屏媒体是否成功嵌入的最直接方法。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考