feat: 新增统一启动屏组件,优化跨平台加载体验
1. 新增splash-screen全局启动屏组件,适配非APP平台的加载过渡 2. 新增splash-state状态管理模块,统一处理启动屏的显示隐藏、软隐藏时序、兜底超时逻辑 3. 重构App.vue和main.js的加载逻辑,替换原有uni.showLoading方案 4. 在首页和空页面挂载启动屏组件,适配不同页面场景 5. 兼容H5平台降级处理,解决main.js挂载前无法渲染组件的问题
This commit is contained in:
225
common/js/splash-state.js
Normal file
225
common/js/splash-state.js
Normal file
@@ -0,0 +1,225 @@
|
||||
// ============================================================
|
||||
// 启动屏单例状态
|
||||
//
|
||||
// 设计要点:
|
||||
// 1. 状态 + 事件双通道: 组件既可 watch visible,也可监听 'splash:hide' 事件
|
||||
// 解决 uni.$emit 在组件挂载前发出就丢失的问题 (memory lesson)
|
||||
// 2. 软隐藏 (softHide): 标记应该 hide, 等组件 mount 后再真正 hide
|
||||
// 解决 onLaunch 跑完 + hide() 早于 page mount 的时序问题
|
||||
// 3. 防重入: show()/hide() 多次调用安全,内部用 guard
|
||||
// 4. 兜底超时: 默认 8s 未关闭则强制 hide,防止卡死
|
||||
// 5. 平台隔离: APP-PLUS 有原生 splash,这里直接返回 false
|
||||
// 6. 跨平台兼容: 同步状态可被 Vue 组件直接 watch
|
||||
// ============================================================
|
||||
|
||||
// APP-PLUS 直接返回 false (有原生启动屏)
|
||||
function needSplash() {
|
||||
// #ifdef APP-PLUS
|
||||
return false;
|
||||
// #endif
|
||||
// #ifndef APP-PLUS
|
||||
return true;
|
||||
// #endif
|
||||
}
|
||||
|
||||
// H5 平台特殊处理: Lang.boot() 在 main.js 中 await, 此时 Vue 还没挂载,
|
||||
// 组件无法渲染, 内部降级为 uni.showLoading 做兜底 (虽然样式较丑但至少有遮罩)
|
||||
function useNativeLoading() {
|
||||
// #ifdef H5
|
||||
return true;
|
||||
// #endif
|
||||
// #ifndef H5
|
||||
return false;
|
||||
// #endif
|
||||
}
|
||||
|
||||
const DEFAULT_TIMEOUT = 8000; // 总兜底超时
|
||||
const MOUNT_GRACE_MS = 1000; // 软隐藏后等组件 mount 的宽限时间
|
||||
|
||||
class SplashState {
|
||||
constructor() {
|
||||
this._visible = false;
|
||||
this._timeoutId = null;
|
||||
this._listeners = [];
|
||||
this._shownAt = 0;
|
||||
// 软隐藏相关
|
||||
this._pendingHide = null; // 软隐藏请求的 opts, 等待组件 mount
|
||||
this._hasMounted = false; // 是否有 splash 组件 mount 过
|
||||
this._mountGraceId = null; // 软隐藏兜底定时器
|
||||
}
|
||||
|
||||
show(opts = {}) {
|
||||
if (!needSplash()) return;
|
||||
if (this._visible) return; // 防重入
|
||||
|
||||
this._visible = true;
|
||||
this._shownAt = Date.now();
|
||||
this._pendingHide = null;
|
||||
this._hasMounted = false;
|
||||
if (this._mountGraceId) {
|
||||
clearTimeout(this._mountGraceId);
|
||||
this._mountGraceId = null;
|
||||
}
|
||||
this._emit('splash:show');
|
||||
|
||||
// H5 降级: 走系统 loading (Vue 还没挂载,组件层无法渲染)
|
||||
if (useNativeLoading()) {
|
||||
try { uni.showLoading({ title: opts.title || '加载中...', mask: true }); } catch (e) {}
|
||||
}
|
||||
|
||||
const timeout = opts.timeout || DEFAULT_TIMEOUT;
|
||||
if (this._timeoutId) {
|
||||
clearTimeout(this._timeoutId);
|
||||
this._timeoutId = null;
|
||||
}
|
||||
this._timeoutId = setTimeout(() => {
|
||||
// 兜底: 超时强制关闭,防止卡死 (走硬隐藏路径, 不等组件)
|
||||
if (this._visible) {
|
||||
console.warn('[splash-state] auto-hide after timeout', timeout);
|
||||
this._doHide({ reason: 'timeout' });
|
||||
}
|
||||
}, timeout);
|
||||
}
|
||||
|
||||
/**
|
||||
* 隐藏 splash
|
||||
* @param {Object} opts
|
||||
* @param {string} opts.reason - 隐藏原因
|
||||
* - 'boot-complete': 软隐藏, 等组件 mount 后再真关 (默认)
|
||||
* - 'timeout': 硬隐藏, 立即关 (兜底用)
|
||||
* - 'manual': 硬隐藏, 立即关
|
||||
* @param {boolean} [opts.soft] - 强制走软隐藏
|
||||
*/
|
||||
hide(opts = {}) {
|
||||
const reason = opts.reason || 'manual';
|
||||
// boot-complete 默认走软隐藏, 避免时序问题
|
||||
const useSoft = opts.soft === true || (opts.soft !== false && reason === 'boot-complete');
|
||||
|
||||
if (useSoft) {
|
||||
this._softHide({ reason });
|
||||
} else {
|
||||
this._doHide({ reason });
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 软隐藏: 标记应该 hide, 等组件 mount
|
||||
* 如果组件 1s 内没 mount, 兜底自动 hide
|
||||
*/
|
||||
_softHide(opts) {
|
||||
if (!this._visible) return; // 已经隐藏了
|
||||
this._pendingHide = opts;
|
||||
|
||||
// 如果组件已经 mount, 立即隐藏
|
||||
if (this._hasMounted) {
|
||||
this._flushPendingHide();
|
||||
return;
|
||||
}
|
||||
|
||||
// 兜底: 1s 内没 mount, 强制隐藏
|
||||
if (this._mountGraceId) clearTimeout(this._mountGraceId);
|
||||
this._mountGraceId = setTimeout(() => {
|
||||
if (this._pendingHide) {
|
||||
this._flushPendingHide();
|
||||
}
|
||||
}, MOUNT_GRACE_MS);
|
||||
}
|
||||
|
||||
/**
|
||||
* 实际隐藏 (硬路径)
|
||||
*/
|
||||
_doHide(opts) {
|
||||
if (!this._visible) return; // 防重入
|
||||
if (this._timeoutId) {
|
||||
clearTimeout(this._timeoutId);
|
||||
this._timeoutId = null;
|
||||
}
|
||||
if (this._mountGraceId) {
|
||||
clearTimeout(this._mountGraceId);
|
||||
this._mountGraceId = null;
|
||||
}
|
||||
this._pendingHide = null;
|
||||
this._visible = false;
|
||||
// H5 降级对应的关闭
|
||||
if (useNativeLoading()) {
|
||||
try { uni.hideLoading(); } catch (e) {}
|
||||
}
|
||||
this._emit('splash:hide', { reason: opts.reason || 'manual' });
|
||||
}
|
||||
|
||||
/**
|
||||
* 真正触发软隐藏
|
||||
*/
|
||||
_flushPendingHide() {
|
||||
const opts = this._pendingHide;
|
||||
this._pendingHide = null;
|
||||
if (this._mountGraceId) {
|
||||
clearTimeout(this._mountGraceId);
|
||||
this._mountGraceId = null;
|
||||
}
|
||||
this._doHide(opts || { reason: 'mount-completed' });
|
||||
}
|
||||
|
||||
/**
|
||||
* 组件 mount 后通知 state 模块
|
||||
* - 标记 _hasMounted
|
||||
* - 如果有 _pendingHide, 触发真关
|
||||
* - H5 降级场景: 立即关掉原生 loading, 让 splash 组件接管视觉
|
||||
*/
|
||||
notifyMounted() {
|
||||
if (this._hasMounted) return;
|
||||
this._hasMounted = true;
|
||||
// H5 降级: 立即关掉原生 loading, 避免和 splash 组件重叠
|
||||
if (useNativeLoading()) {
|
||||
try { uni.hideLoading(); } catch (e) {}
|
||||
}
|
||||
if (this._pendingHide) {
|
||||
// 给组件一帧时间渲染, 再隐藏 (避免一帧闪烁)
|
||||
setTimeout(() => this._flushPendingHide(), 50);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 组件 unmount 时通知 (用于 _hasMounted 状态管理)
|
||||
* 目前保留 _hasMounted=true, 因为一般只有 tab 页有 splash 组件, 不会动态增减
|
||||
*/
|
||||
notifyUnmounted() {
|
||||
// 不重置 _hasMounted, 因为软隐藏的 _pendingHide 处理不依赖 unmount
|
||||
}
|
||||
|
||||
isShow() {
|
||||
return this._visible;
|
||||
}
|
||||
|
||||
hasPendingHide() {
|
||||
return this._pendingHide != null;
|
||||
}
|
||||
|
||||
elapsed() {
|
||||
if (!this._visible) return 0;
|
||||
return Date.now() - this._shownAt;
|
||||
}
|
||||
|
||||
on(event, fn) {
|
||||
if (!this._listeners[event]) this._listeners[event] = [];
|
||||
this._listeners[event].push(fn);
|
||||
}
|
||||
|
||||
off(event, fn) {
|
||||
if (!this._listeners[event]) return;
|
||||
this._listeners[event] = this._listeners[event].filter(f => f !== fn);
|
||||
}
|
||||
|
||||
_emit(event, payload) {
|
||||
const arr = this._listeners[event];
|
||||
if (!arr || !arr.length) return;
|
||||
for (let i = 0; i < arr.length; i++) {
|
||||
try { arr[i](payload); } catch (e) { console.warn('[splash-state] listener err', e); }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const splashState = new SplashState();
|
||||
|
||||
export default splashState;
|
||||
export { splashState };
|
||||
Reference in New Issue
Block a user