# 梗中作乐 V1.0 - 源代码文档（第 1 部分）

软件名称：梗中作乐
版本号：V1.0

---

## 第 1 部分：程序入口与视图管理

本部分包含 3 个源文件，是整个小游戏的启动入口、加载页与全局视图调度器。

### 1.1 程序主入口 (assets/main.ts)

```typescript
import { _decorator, Component, Prefab, AudioClip } from 'cc';
import { ViewManager } from './scripts/core/ViewManager';
import { ToastManager } from './scripts/utils/ToastManager';
import { AudioManager } from './scripts/utils/AudioManager';
import { ShareLaunchHandler } from './scripts/utils/ShareLaunchHandler';
const { ccclass, property } = _decorator;

/**
 * 主入口脚本
 * 负责初始化 ViewManager 并注册页面
 */
@ccclass('main')
export class main extends Component {
    @property({ type: Prefab, tooltip: '首页预制体' })
    pageHomePrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: '关卡页面预制体' })
    pageLevelPrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: '写关卡页面预制体' })
    pageWriteLevelsPrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: '预览试卷页面预制体' })
    pagePreviewLevelsPrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: '挑战数据页面预制体' })
    pagePKDataPrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: '挑战详情页面预制体' })
    pagePKDetailPrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: '挑战结算页面预制体' })
    pagePKEndPrefab: Prefab | null = null;

    @property({ type: Prefab, tooltip: 'Toast 预制体' })
    toastPrefab: Prefab | null = null;

    @property({ type: AudioClip, tooltip: '通用按钮点击音效' })
    buttonClickAudio: AudioClip | null = null;

    /**
     * onLoad 比 start 更早执行
     * 确保 ViewManager 在 PageLoading.start() 之前初始化
     */
    onLoad() {
        this._initViewManager();
    }

    /**
     * 初始化页面管理器
     */
    private _initViewManager(): void {
        // 初始化 ViewManager，绑定 Canvas 作为页面容器
        ViewManager.instance.init(this.node);

        // 注册页面配置（通过编辑器属性引用预制体）
        if (this.pageHomePrefab) {
            ViewManager.instance.register('PageHome', {
                prefab: this.pageHomePrefab,
                cache: true,
                zIndex: 0
            });
        }

        if (this.pageLevelPrefab) {
            ViewManager.instance.register('PageLevel', {
                prefab: this.pageLevelPrefab,
                cache: true,
                zIndex: 1
            });
        }

        if (this.pageWriteLevelsPrefab) {
            ViewManager.instance.register('PageWriteLevels', {
                prefab: this.pageWriteLevelsPrefab,
                cache: true,
                zIndex: 2
            });
        }

        if (this.pagePreviewLevelsPrefab) {
            ViewManager.instance.register('PagePreviewLevels', {
                prefab: this.pagePreviewLevelsPrefab,
                cache: true,
                zIndex: 3
            });
        }

        if (this.pagePKDataPrefab) {
            ViewManager.instance.register('PagePKData', {
                prefab: this.pagePKDataPrefab,
                cache: true,
                zIndex: 3
            });
        }

        if (this.pagePKDetailPrefab) {
            ViewManager.instance.register('PagePKDetail', {
                prefab: this.pagePKDetailPrefab,
                cache: true,
                zIndex: 4
            });
        }

        if (this.pagePKEndPrefab) {
            ViewManager.instance.register('PagePKEnd', {
                prefab: this.pagePKEndPrefab,
                cache: true,
                zIndex: 3
            });
        }

        // 初始化 Toast 管理器
        if (this.toastPrefab) {
            ToastManager.instance.init(this.toastPrefab, this.node);
        }

        AudioManager.instance.init(this.buttonClickAudio, this.node);

        // 注册 wx.onShow / wx.onHide：
        // 用户把小游戏退到后台后再点击好友分享卡片，能拿到最新的 shareCode 并直达分享挑战关卡。
        // 必须在 PageLoading 跑之前注册，这样初始 launch 中的 shareCode 也会被作为种子记下。
        ShareLaunchHandler.instance.init();
    }
}
```

### 1.2 加载页 (assets/PageLoading.ts)

```typescript
import { _decorator, Component, ProgressBar, Label, assetManager } from 'cc';
import type { AssetManager } from 'cc';
import { ViewManager } from './scripts/core/ViewManager';
import { LevelDataManager } from './scripts/utils/LevelDataManager';
import { AuthManager } from './scripts/utils/AuthManager';
import { ShareManager } from './scripts/utils/ShareManager';
import { ShareLaunchHandler } from './scripts/utils/ShareLaunchHandler';
import { WxSDK } from './scripts/utils/WxSDK';
const { ccclass, property } = _decorator;

/**
 * 页面加载组件
 * 负责用户登录、预加载资源并显示加载进度
 * 流程：登录 + game-data → 拿到 nextLevel → 加载首关图片 → 进入首页
 */
@ccclass('PageLoading')
export class PageLoading extends Component {
    private static readonly FONT_BUNDLE_NAME = 'fonts';

    @property(ProgressBar)
    progressBar: ProgressBar | null = null;

    @property(Label)
    statusLabel: Label | null = null;

    start() {
        this._startPreload();
    }

    private async _startPreload(): Promise<void> {
        if (this.progressBar) {
            this.progressBar.progress = 0;
        }

        this._updateStatusLabel('正在加载...');

        // 阶段0: 主动触发微信隐私授权。分享挑战直达关卡时也会先经过这里。
        this._updateStatusLabel('正在确认隐私授权...');
        const privacyAuthorized = await WxSDK.ensurePrivacyAuthorized();
        if (!privacyAuthorized) {
            console.warn('[PageLoading] 用户未同意隐私授权，继续加载基础流程');
        }

        // 阶段1: 登录 + 获取 game-data（含 nextLevel）
        this._updateProgress(0);
        this._updateStatusLabel('正在连接服务器...');

        const loginSuccess = await AuthManager.instance.initialize();

        if (loginSuccess) {
            console.log('[PageLoading] 用户登录成功');
        } else {
            console.warn('[PageLoading] 登录失败，继续离线模式');
        }

        this._updateProgress(0.2);

        // 阶段2: 加载首关图片（如果有 nextLevel）
        const nextLevel = AuthManager.instance.nextLevel;
        let levelSuccess = false;

        if (nextLevel) {
            levelSuccess = await LevelDataManager.instance.initialize(nextLevel, (progress, message) => {
                // 关卡图片加载占 20%-80% 进度
                this._updateProgress(0.2 + progress * 0.6);
                this._updateStatusLabel(message);
            });

            if (!levelSuccess) {
                this._updateStatusLabel('资源加载失败，请重新打开游戏');
                return;
            }
        } else if (loginSuccess) {
            // nextLevel 为 null → 全部通关（或服务端无关卡）
            console.log('[PageLoading] 全部通关或无可用关卡');
            this._updateProgress(0.8);
        } else {
            // 登录失败且没有 nextLevel
            this._updateStatusLabel('加载失败，请重新打开游戏');
            return;
        }

        // 阶段3: 加载字体分包
        const fontSuccess = await this._loadFontBundle();
        if (!fontSuccess) {
            this._updateStatusLabel('字体资源加载失败，请重新打开游戏');
            return;
        }

        // 检测分享码：从微信启动参数中获取
        const shareCode = WxSDK.getShareCodeFromLaunch();
        if (shareCode && loginSuccess) {
            this._updateStatusLabel('正在加载挑战关卡...');
            const joinSuccess = await ShareManager.instance.joinShare(shareCode);
            if (joinSuccess) {
                // 把启动 shareCode 同步给 ShareLaunchHandler，
                // 避免 wx.onShow 在初始展示时拿到同一个 code 又走一遍 join。
                ShareLaunchHandler.instance.markActiveShareCode(shareCode);
                this._updateProgress(1);
                this._updateStatusLabel('加载完成');
                // 跳过首页，直接进入分享挑战关卡
                ViewManager.instance.open('PageLevel', {
                    params: { shareMode: true },
                    onComplete: () => {
                        this.node.destroy();
                    },
                });
                return;
            }
            console.warn('[PageLoading] 加入分享失败，进入正常模式');
        }

        // 正常流程：预加载 PageHome (82-100%)
        ViewManager.instance.preload('PageHome',
            (progress) => {
                this._updateProgress(0.82 + progress * 0.18);
                this._updateStatusLabel('正在加载界面资源...');
            },
            () => {
                this._onPreloadComplete();
            }
        );
    }

    private _updateProgress(progress: number): void {
        if (this.progressBar) {
            this.progressBar.progress = progress;
        }
    }

    private _updateStatusLabel(message: string): void {
        if (this.statusLabel) {
            this.statusLabel.string = message;
        }
    }

    private _onPreloadComplete(): void {
        this._updateProgress(1);
        this._updateStatusLabel('加载完成');

        // 兜底：如果在 PageLoading 还在 preload 期间，wx.onShow 已经把游戏切到了分享态
        // （ShareLaunchHandler 已经 joinShare 成功），这里就不应再覆盖回首页，
        // 否则用户点了好友分享卡片却看到 PageHome。
        if (ShareManager.instance.isShareMode) {
            console.log('[PageLoading] 检测到分享态已激活，跳过首页直达 PageLevel');
            ViewManager.instance.open('PageLevel', {
                params: { shareMode: true },
                onComplete: () => {
                    this.node.destroy();
                },
            });
            return;
        }

        ViewManager.instance.open('PageHome', {
            onComplete: () => {
                this.node.destroy();
            }
        });
    }

    /**
     * 加载字体分包，避免字体资源进入小游戏主包
     */
    private _loadFontBundle(): Promise<boolean> {
        const bundleName = PageLoading.FONT_BUNDLE_NAME;
        const cachedBundle = assetManager.getBundle(bundleName);
        if (cachedBundle) {
            console.log(`[PageLoading] 字体分包已加载: ${bundleName}`);
            this._updateProgress(0.82);
            return Promise.resolve(true);
        }

        this._updateStatusLabel('正在加载字体资源...');
        this._updateProgress(0.8);

        return new Promise((resolve) => {
            assetManager.loadBundle(bundleName, (err: Error | null, bundle: AssetManager.Bundle | null) => {
                if (err || !bundle) {
                    console.error(`[PageLoading] 字体分包加载失败: ${bundleName}`, err);
                    resolve(false);
                    return;
                }

                console.log(`[PageLoading] 字体分包加载完成: ${bundleName}`);
                this._updateProgress(0.82);
                resolve(true);
            });
        });
    }
}
```

### 1.3 视图管理器 (assets/scripts/core/ViewManager.ts)

```typescript
import { _decorator, Node, Prefab, instantiate, error } from 'cc';
import { BaseView, ViewConfig, ViewOptions } from './BaseView';
const { ccclass } = _decorator;

/**
 * 已注册的页面配置映射
 */
interface RegisteredView {
    config: ViewConfig;
}

/**
 * 页面管理器
 * 单例模式，统一管理页面的注册、打开、关闭、返回等操作
 */
@ccclass('ViewManager')
export class ViewManager {
    /** 单例实例 */
    private static _instance: ViewManager | null = null;

    /** 获取单例 */
    public static get instance(): ViewManager {
        if (!ViewManager._instance) {
            ViewManager._instance = new ViewManager();
        }
        return ViewManager._instance;
    }

    /** 页面容器节点 */
    private _container: Node | null = null;

    /** 已注册的页面配置 */
    private _registeredViews: Map<string, RegisteredView> = new Map();

    /** 页面栈 */
    private _viewStack: BaseView[] = [];

    /** 页面实例缓存（用于缓存模式的页面） */
    private _viewCache: Map<string, BaseView> = new Map();

    /**
     * 初始化管理器
     * @param container 页面容器节点（通常是 Canvas）
     */
    init(container: Node): void {
        this._container = container;
    }

    /**
     * 获取当前容器
     */
    getContainer(): Node | null {
        return this._container;
    }

    /**
     * 注册页面
     * @param viewId 页面唯一标识
     * @param config 页面配置
     */
    register(viewId: string, config: ViewConfig): void {
        if (this._registeredViews.has(viewId)) {
            error(`ViewManager: 页面 "${viewId}" 已注册`);
            return;
        }

        this._registeredViews.set(viewId, {
            config: {
                cache: true,  // 默认缓存
                zIndex: 0,    // 默认层级
                ...config
            }
        });
    }

    /**
     * 批量注册页面
     * @param views 页面配置映射
     */
    registerAll(views: Record<string, ViewConfig>): void {
        for (const [viewId, config] of Object.entries(views)) {
            this.register(viewId, config);
        }
    }

    /**
     * 打开页面
     * @param viewId 页面唯一标识
     * @param options 打开选项
     */
    open(viewId: string, options?: ViewOptions): void {
        if (!this._container) {
            const err = new Error('ViewManager: 未初始化，请先调用 init()');
            options?.onError?.(err);
            return;
        }

        const registered = this._registeredViews.get(viewId);
        if (!registered) {
            const err = new Error(`ViewManager: 页面 "${viewId}" 未注册`);
            options?.onError?.(err);
            return;
        }

        // 检查是否有缓存的实例
        const cachedView = this._viewCache.get(viewId);
        if (cachedView && cachedView.node.isValid) {
            this._showView(cachedView, options);
            return;
        }

        // 直接使用预制体引用实例化
        this._instantiateView(viewId, registered.config.prefab, options);
    }

    /**
     * 实例化视图
     */
    private _instantiateView(viewId: string, prefab: Prefab, options?: ViewOptions): void {
        if (!this._container) return;

        const registered = this._registeredViews.get(viewId);
        if (!registered) return;

        const node = instantiate(prefab);
        const view = node.getComponent(BaseView);

        if (!view) {
            error(`ViewManager: 预制体 "${viewId}" 缺少 BaseView 组件`);
            node.destroy();
            options?.onError?.(new Error('缺少 BaseView 组件'));
            return;
        }

        // 设置视图属性
        view.viewId = viewId;
        view.config = registered.config;
        view.setParams(options?.params);

        // 设置层级
        node.setSiblingIndex(registered.config.zIndex || 0);

        // 添加到容器
        this._container.addChild(node);

        // 调用加载回调
        view.onViewLoad();

        // 缓存视图实例
        if (registered.config.cache) {
            this._viewCache.set(viewId, view);
        }

        // 显示视图
        this._showView(view, options);
    }

    /**
     * 显示视图
     */
    private _showView(view: BaseView, options?: ViewOptions): void {
        // 隐藏当前页面
        const currentView = this.getCurrentView();
        if (currentView && currentView !== view) {
            currentView._doHide();
        }

        // 设置参数
        if (options?.params !== undefined) {
            view.setParams(options?.params);
        }

        // 入栈
        if (!this._viewStack.includes(view)) {
            this._viewStack.push(view);
        }

        // 显示
        view._doShow();

        // 回调
        options?.onComplete?.(view);
    }

    /**
     * 关闭当前页面
     * @param options 关闭选项
     */
    close(options?: { destroy?: boolean }): void {
        const currentView = this._viewStack.pop();
        if (!currentView) return;

        const shouldDestroy = options?.destroy ?? !currentView.config?.cache;
        this._hideAndDestroyView(currentView, shouldDestroy);

        // 显示上一页
        const prevView = this.getCurrentView();
        if (prevView) {
            prevView._doShow();
        }
    }

    /**
     * 返回上一页（close 的别名）
     */
    back(): void {
        this.close();
    }

    /**
     * 替换当前页面
     * @param viewId 新页面标识
     * @param options 打开选项
     */
    replace(viewId: string, options?: ViewOptions): void {
        const currentView = this.getCurrentView();
        if (currentView) {
            this._viewStack.pop();
            const shouldDestroy = !currentView.config?.cache;
            this._hideAndDestroyView(currentView, shouldDestroy);
        }

        this.open(viewId, options);
    }

    /**
     * 隐藏并销毁视图（内部方法）
     */
    private _hideAndDestroyView(view: BaseView, shouldDestroy: boolean): void {
        view._doHide();
        if (shouldDestroy) {
            this._viewCache.delete(view.viewId);
            view._doDestroy();
        }
    }

    /**
     * 获取当前页面
     */
    getCurrentView(): BaseView | null {
        return this._viewStack.length > 0
            ? this._viewStack[this._viewStack.length - 1]
            : null;
    }

    /**
     * 获取页面栈
     */
    getViewStack(): BaseView[] {
        return [...this._viewStack];
    }

    /**
     * 清空所有页面
     */
    clearAll(): void {
        // 从栈顶开始销毁
        while (this._viewStack.length > 0) {
            const view = this._viewStack.pop()!;
            const shouldDestroy = !view.config?.cache;
            this._hideAndDestroyView(view, shouldDestroy);
        }

        // 销毁缓存的页面
        for (const view of this._viewCache.values()) {
            if (view.node.isValid) {
                view._doDestroy();
            }
        }

        this._viewCache.clear();
    }

    /**
     * 预加载页面预制体（主包资源已随游戏加载，此方法仅为兼容性保留）
     * @param viewId 页面标识
     * @param onProgress 进度回调
     * @param onComplete 完成回调
     */
    preload(viewId: string, onProgress?: (progress: number) => void, onComplete?: () => void): void {
        const registered = this._registeredViews.get(viewId);
        if (!registered) {
            error(`ViewManager: 页面 "${viewId}" 未注册`);
            onComplete?.();
            return;
        }

        // 主包资源已加载，直接回调
        onProgress?.(1);
        onComplete?.();
    }

    /**
     * 批量预加载页面
     * @param viewIds 页面标识数组
     * @param onProgress 总进度回调 (0-1)
     * @param onComplete 完成回调
     */
    preloadAll(viewIds: string[], onProgress?: (progress: number) => void, onComplete?: () => void): void {
        if (viewIds.length === 0) {
            onProgress?.(1);
            onComplete?.();
            return;
        }

        let completed = 0;
        const total = viewIds.length;

        for (const viewId of viewIds) {
            this.preload(viewId, () => {
                completed++;
                onProgress?.(completed / total);
                if (completed === total) {
                    onComplete?.();
                }
            });
        }
    }
}
```