企业官网建设流程全解析

Meteor 移动端体验包 mobile-experience 完整指南：状态栏与启动屏的默认配置与自定义

【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor

本篇技术指南围绕 Meteor 官方仓库中的 mobile-experience 聚合包展开，它是一组面向 Cordova/PhoneGap 移动端构建的“体验默认值”包，在打包原生 Android 与 iOS 应用时自动生效。读完本文，你将掌握 mobile-experience 的组成与激活机制、通过mobile-config.js定制状态栏外观、使用LaunchScreen.hold()/release()精确控制启动屏隐藏时机，以及这些能力在源码层面的实现原理。

一、mobile-experience 是什么

mobile-experience 是 Meteor 官方提供的一个“伞形（umbrella）”包。从 package.js 可以看出，它自身不包含任何业务代码，职责是把一组 Cordova 专属的包聚合起来，为移动端应用提供开箱即用的体验默认值：

• mobile-status-bar：避免系统状态栏信息遮挡应用内容；
• launch-screen：用启动图（launch image / splash screen）覆盖应用，让用户看不到界面加载过程。

它的核心激活规则是：只有当你在构建原生 Android 或 iOS 应用时才生效。这是因为聚合关系通过 Cordova 环境限定实现——在 package.js 中，mobile-status-bar以web.cordova架构被api.imply引入，而launch-screen则被全平台引入（原因见下文“launch-screen 的全平台引入设计”）。

历史背景：meteor-platform 拆分

mobile-experience 诞生于 Meteor 1.2.0 对meteor-platform聚合包的拆分。在 tools/upgraders.js 的1.2.0-meteor-platform-split升级器中可以看到，旧项目中的meteor-platform会被自动替换为一组新包，其中就包括meteor-base、mobile-experience、mongo、blaze-html-templates等。也就是说，从 1.2.0 起，新创建的 Meteor 应用默认就包含 mobile-experience。

二、状态栏默认体验：mobile-status-bar

2.1 包的作用与依赖

mobile-status-bar 在 Meteor Phonegap/Cordova 应用中提供状态栏定制能力。目前它的实现方式非常轻量：直接暴露标准的cordova-plugin-statusbar插件并附带一组默认值。从 package.js 可以看到，它通过Cordova.depends锁定插件版本：

Cordova.depends({ 'cordova-plugin-statusbar': '2.4.3' });

这意味着只要应用包含 mobile-experience，构建 Cordova 应用时就会自动拉取并配置该原生插件，无需手动meteor add cordova:cordova-plugin-statusbar。

2.2 在 mobile-config.js 中定制状态栏

你可以在应用的mobile-config.js文件中通过App.setPreference设置状态栏偏好：

App.setPreference('StatusBarOverlaysWebView', 'false'); App.setPreference('StatusBarBackgroundColor', '#000000');

两个最常用的偏好项含义如下：

需要注意的是：App.setPreference传入的键值在原生层面最终会写入 Cordova 项目的配置文件，因此键名与cordova-plugin-statusbar插件的偏好项保持一致，更多原生偏好项可查阅该插件的官方文档。

三、启动屏默认体验：launch-screen

3.1 包的作用与依赖

launch-screen 是一个仅面向移动端的包，它提供了一套 API，用于推迟启动屏的移除时机、推迟应用变为可见的时刻。典型场景是：应用在首次渲染 UI 时避免用户看到白屏——先把启动图盖在屏幕上，等界面就绪后再撤掉。

同样地，它在 package.js 中通过Cordova.depends依赖了原生插件：

Cordova.depends({ 'cordova-plugin-splashscreen': '6.0.0' });

3.2 launch-screen 的全平台引入设计

这是理解 mobile-experience 的关键设计细节之一。在 mobile-experience/package.js 中，launch-screen没有限定web.cordova架构，而是全平台引入，注释给出了明确理由：

不含 Cordova 时它什么也不做，但我们到处引入它，这样你就不需要在每次LaunchScreen调用周围写一堆 if 判断。

配合 mobile-launch-screen.js 的实现，这个设计得以成立——LaunchScreen.hold()在非 Cordova 环境下（!Meteor.isCordova）会直接返回一个release为 noop（空操作）的句柄，因此你可以在 Web 和移动端共用同一份代码而无需分支判断。

3.3 极简用法：什么都不用配置

launch-screen 的核心卖点是零配置：

// 只需添加包，无需任何特殊配置

当包被添加后，应用会一直持有启动屏，直到满足以下任一条件：

• body模板渲染完成（默认路径）；
• 如果应用使用iron:router，则等待第一个路由渲染完成。

这段逻辑位于 default-behavior.js 中，下面会展开其实现细节。

3.4 手动控制：hold / release 句柄

当默认的释放时机不满足需求、你还需要等待其他 UI 元素加载完成时，可以手动控制启动屏的释放：

• 在客户端代码的顶层调用var handle = LaunchScreen.hold()增加一个“持有”；
• 当 UI 就绪后调用handle.release()释放该持有。

只有所有持有都被释放后，启动屏才会被移除。

示例：等待某个模板渲染完成后再释放启动屏。

// 放在仅客户端执行的 js 文件中 var handle = LaunchScreen.hold(); Template.myUI.onRendered(function () { handle.release(); });

应用内的任意代码、以及应用依赖的包，都可以多次调用LaunchScreen.hold()；每个hold()返回独立的句柄，必须对全部句柄都调用release()，启动屏才会隐藏。

3.5 源码级原理解析

引用计数与一次性语义

LaunchScreen的实现位于 mobile-launch-screen.js，核心是一个引用计数模型：

• 模块级变量holdCount记录当前持有效果的数量，alreadyHidden标记启动屏是否已隐藏；
• hold()在非 Cordova 环境返回 noop 句柄；若启动屏已被隐藏（alreadyHidden为真），再调用hold()会抛出错误"Can't show launch screen once it's hidden"；
• 每次hold()令holdCount++，release()通过released标志保证幂等（同一句柄重复 release 不会重复递减），当holdCount归零且navigator.splashscreen存在时，调用navigator.splashscreen.hide()真正隐藏原生启动屏，并置alreadyHidden = true。

默认行为的实现路径

default-behavior.js 是“零配置”体验的来源，其执行顺序为：

1. 应用加载时立即LaunchScreen.hold()，反映“Meteor 移动应用总是以启动屏可见状态启动”的事实；
2. 在Meteor.startup回调中按环境分流：
   • 若没有 BlazeTemplate（即未使用 templating），直接release()；
   • 若检测到iron:router包，则挂接Router.onAfterAction，首个路由动作完成后释放（代码注释说明这段逻辑本应放在 iron:router 内部，因在Meteor.startup块中，未在 package.js 里对 iron:router 声明 weak 依赖也是安全的）；
   • 否则监听Template.body.onRendered释放；
3. 兜底保护：如果Template.body因某些 bug 始终未渲染，则设置 6 秒定时器强制release()。注释指出这一时间与 Android（而非 iOS）上 Cordova 应用隐藏启动屏的既有超时行为一致。

可见默认行为覆盖了 Web（无原生启动屏）、Blaze 模板、iron:router 三种典型场景，并带超时兜底，这正是它作为“好默认值”的体现。

四、把两者组合使用：一个完整的示例

把两个子包组合起来，一个典型的移动端启动体验配置如下：

mobile-config.js中定制状态栏与启动图偏好：

App.setPreference('StatusBarOverlaysWebView', 'false'); App.setPreference('StatusBarBackgroundColor', '#000000'); App.setPreference('SplashScreen', 'screen'); App.setPreference('SplashScreenDelay', '5000');

客户端代码中等待真实 UI 就绪后再释放启动屏：

// client/main.js（仅客户端） var handle = LaunchScreen.hold(); Template.mainLayout.onRendered(function () { handle.release(); });

配合 mobile-experience 的聚合能力，上述代码在 Android/iOS 原生构建中自动获得：状态栏不遮挡内容、启动屏在 UI 就绪前一直可见；而在 Web 端运行时，LaunchScreen.hold()返回 noop 句柄，整段代码无需任何分支即可安全运行。

五、常见问题与注意事项

• 只在原生构建中生效：mobile-status-bar 以web.cordova架构引入，浏览器端不会注入任何状态栏逻辑；
• 不要在启动屏隐藏后再 hold：此时会抛出"Can't show launch screen once it's hidden"，务必把hold()放在客户端代码顶层、应用启动阶段；
• release 是幂等的：同一句柄重复调用release()是安全的，内部有released标志防止重复计数；
• 依赖版本由包锁定：cordova-plugin-statusbar@2.4.3与cordova-plugin-splashscreen@6.0.0由各包通过Cordova.depends固定，升级需跟随 Meteor 包版本。

六、相关资源

• 聚合包定义与说明：packages/mobile-experience/package.js、packages/mobile-experience/README.md
• 状态栏子包：packages/mobile-status-bar/README.md、packages/mobile-status-bar/package.js
• 启动屏子包文档：packages/launch-screen/README.md
• 启动屏实现源码：packages/launch-screen/mobile-launch-screen.js、packages/launch-screen/default-behavior.js
• meteor-platform 拆分历史：tools/upgraders.js

【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor