feat: 接入激励视频

软著源代码/08-通关弹窗与提示.md

@@ -0,0 +1,710 @@
+# 梗中作乐 V1.0 - 源代码文档（第 8 部分）
+
+软件名称：梗中作乐
+版本号：V1.0
+
+---
+
+## 第 8 部分：通关弹窗与轻提示
+
+本部分包含通关庆祝弹窗、预览关卡项组件、轻提示组件以及 Toast 管理工具。
+
+### 8.1 通关弹窗 (assets/prefabs/PassModal.ts)
+
+```typescript
+import { _decorator, Node, Label, AudioClip, AudioSource, view, UITransform, Size, ProgressBar, tween, Tween } from 'cc';
+import { BaseModal } from 'db://assets/scripts/core/BaseModal';
+import { WxSDK } from 'db://assets/scripts/utils/WxSDK';
+import { AudioManager } from 'db://assets/scripts/utils/AudioManager';
+const { ccclass, property } = _decorator;
+
+/**
+ * PassModal 回调接口
+ */
+export interface PassModalCallbacks {
+    /** 点击下一关回调 */
+    onNextLevel?: () => void;
+    /** 点击分享回调 */
+    onShare?: () => void;
+    /** 点击返回主页回调 */
+    onHome?: () => void;
+}
+
+export interface PassModalTitleInfo {
+    titleText?: string;
+    nextTitleProgress?: number;
+    progressText?: string;
+}
+
+interface PassModalParams {
+    levelIndex?: number;
+    /** 下一步按钮文案，不传时使用 prefab 默认文案 */
+    nextButtonText?: string;
+    titleInfo?: PassModalTitleInfo;
+    /**
+     * 通关前的称号信息。传入后，本次显示会把进度条从该起点动画到 titleInfo 的终点；
+     * 起点与终点 titleText 不同则分两段（先填满当前等级，再切换到新等级后填到目标进度）。
+     * 分享模式等无本地进度变化的场景不要传。
+     */
+    previousTitleInfo?: PassModalTitleInfo;
+}
+
+/**
+ * 通关弹窗组件
+ * 继承 BaseModal，显示通关成功弹窗，提供"下一关"和"分享给好友"两个按钮
+ */
+@ccclass('PassModal')
+export class PassModal extends BaseModal {
+    /** 静态常量：弹窗层级 */
+    public static readonly MODAL_Z_INDEX = 999;
+
+    /** 下一关按钮 */
+    @property(Node)
+    nextLevelButton: Node | null = null;
+
+    /** 返回主页按钮 */
+    @property(Node)
+    settingButton: Node | null = null;
+
+    /** 分享按钮 */
+    @property(Node)
+    shareButton: Node | null = null;
+
+    /** 称号文字 */
+    @property(Label)
+    titleLevelLabel: Label | null = null;
+
+    /** 距离下一个称号的进度 */
+    @property(ProgressBar)
+    titleProgressBar: ProgressBar | null = null;
+
+    /** 进度提示文案 */
+    @property(Label)
+    progressLabel: Label | null = null;
+
+    /** 称号进度游标 */
+    @property(Node)
+    progressAnchor: Node | null = null;
+
+    /** 通关音效 */
+    @property(AudioClip)
+    successAudio: AudioClip | null = null;
+
+    /** 进度条动画起始前的等待时长（秒），等弹窗开场动画稳定后再开始 */
+    private static readonly PROGRESS_ANIM_START_DELAY = 0.4;
+    /** 单段进度条填充动画时长（秒） */
+    private static readonly PROGRESS_ANIM_SEGMENT_DURATION = 0.6;
+    /** 跨称号切换时的等级信息刷新停顿（秒），让玩家看清称号变更 */
+    private static readonly PROGRESS_ANIM_LEVELUP_PAUSE = 0.12;
+
+    /** 回调函数 */
+    private _callbacks: PassModalCallbacks = {};
+
+    /** 缓存的屏幕尺寸 */
+    private _screenSize: Size | null = null;
+
+    /** 称号展示数据（终态） */
+    private _titleInfo: PassModalTitleInfo = {
+        titleText: '冷场小白1级',
+        nextTitleProgress: 0,
+        progressText: '还差3题，解锁新成就等级'
+    };
+
+    /** 动画起点。为 null 表示不做进度动画，直接展示终态 */
+    private _previousTitleInfo: PassModalTitleInfo | null = null;
+
+    /** 进度动画所绑定的对象，用于 Tween.stopAllByTarget */
+    private readonly _progressTweenTarget: { progress: number } = { progress: 0 };
+
+    /** 下一步按钮文案，为 null 时保留 prefab 默认值 */
+    private _nextButtonText: string | null = null;
+
+    /** 进度游标 0% 时的本地 X 坐标，根据 ProgressBar Bar 子节点的左端推导出来 */
+    private _progressAnchorStartX: number | null = null;
+
+    setParams(params: PassModalParams): void {
+        super.setParams(params);
+
+        // previousTitleInfo 可以显式传 null 来禁用动画；undefined 表示"保持已有状态"
+        if (params && 'previousTitleInfo' in params) {
+            this._previousTitleInfo = params.previousTitleInfo ?? null;
+        }
+
+        if (params?.titleInfo) {
+            this.setTitleInfo(params.titleInfo);
+        }
+
+        if (params && 'nextButtonText' in params) {
+            this._nextButtonText = params.nextButtonText ?? null;
+            this._applyNextButtonText();
+        }
+    }
+
+    /**
+     * 设置回调函数
+     */
+    setCallbacks(callbacks: PassModalCallbacks): void {
+        this._callbacks = callbacks;
+    }
+
+    /**
+     * 设置称号体系展示数据
+     */
+    setTitleInfo(titleInfo: PassModalTitleInfo): void {
+        this._titleInfo = {
+            ...this._titleInfo,
+            ...titleInfo
+        };
+        this._refreshTitleView();
+    }
+
+    /**
+     * 页面首次加载时调用
+     */
+    onViewLoad(): void {
+        console.log('[PassModal] onViewLoad');
+        this._resolveNodes();
+        this._resolveProgressAnchor();
+        this._cacheProgressAnchorStartX();
+        this._bindButtonEvents();
+    }
+
+    /**
+     * 页面每次显示时调用
+     */
+    onViewShow(): void {
+        super.onViewShow();
+        this._updateWidget();
+        this._refreshTitleView();
+        this._applyNextButtonText();
+        this._playSuccessSound();
+        this._playProgressAnimation();
+    }
+
+    /**
+     * 页面隐藏时调用
+     */
+    onViewHide(): void {
+        super.onViewHide();
+        this._stopProgressAnimation();
+    }
+
+    /**
+     * 页面销毁时调用
+     */
+    onViewDestroy(): void {
+        this._stopProgressAnimation();
+        this._unbindButtonEvents();
+    }
+
+    /**
+     * 设置弹窗尺寸为全屏
+     * 动态实例化后，手动设置节点尺寸覆盖整个屏幕
+     */
+    private _updateWidget(): void {
+        // 缓存屏幕尺寸，避免重复计算
+        if (!this._screenSize) {
+            this._screenSize = view.getVisibleSize();
+        }
+
+        const uiTransform = this.node.getComponent(UITransform);
+        if (uiTransform) {
+            uiTransform.setContentSize(this._screenSize.width, this._screenSize.height);
+        }
+    }
+
+    /**
+     * 绑定按钮事件
+     */
+    private _bindButtonEvents(): void {
+        if (this.nextLevelButton) {
+            this.nextLevelButton.on(Node.EventType.TOUCH_END, this._onNextLevelClick, this);
+        }
+        if (this.settingButton) {
+            this.settingButton.on(Node.EventType.TOUCH_END, this._onHomeClick, this);
+        }
+        if (this.shareButton) {
+            this.shareButton.on(Node.EventType.TOUCH_END, this._onShareClick, this);
+        }
+    }
+
+    /**
+     * 解除按钮事件绑定
+     */
+    private _unbindButtonEvents(): void {
+        // 节点可能在销毁过程中已被置空，需要检查 isValid
+        if (this.nextLevelButton && this.nextLevelButton.isValid) {
+            this.nextLevelButton.off(Node.EventType.TOUCH_END, this._onNextLevelClick, this);
+        }
+        if (this.settingButton && this.settingButton.isValid) {
+            this.settingButton.off(Node.EventType.TOUCH_END, this._onHomeClick, this);
+        }
+        if (this.shareButton && this.shareButton.isValid) {
+            this.shareButton.off(Node.EventType.TOUCH_END, this._onShareClick, this);
+        }
+    }
+
+    private _resolveNodes(): void {
+        this.nextLevelButton = this.nextLevelButton ?? this.node.getChildByName('Button') ?? null;
+        this.settingButton = this.settingButton ?? this.node.getChildByName('SettingButton') ?? null;
+        this.shareButton = this.shareButton ?? this.node.getChildByName('Share') ?? null;
+    }
+
+    /**
+     * 播放通关音效
+     */
+    private _playSuccessSound(): void {
+        if (!this.successAudio) {
+            return;
+        }
+
+        const audioSource = this.node.getComponent(AudioSource) ?? this.node.addComponent(AudioSource);
+        audioSource.playOneShot(this.successAudio);
+    }
+
+    /**
+     * 用当前 _titleInfo 刷新视图（称号、进度条、进度文案）
+     * 进度条动画运行时，会由动画控制进度值，这里仍然把进度写为终态
+     * —— _playProgressAnimation 会在动画开始前覆盖为起点。
+     */
+    private _refreshTitleView(): void {
+        this._applyTitleText(this._titleInfo.titleText);
+        this._applyProgressText(this._titleInfo.progressText);
+        this._applyProgressValue(this._titleInfo.nextTitleProgress);
+    }
+
+    private _applyTitleText(text: string | undefined): void {
+        if (this.titleLevelLabel && text !== undefined) {
+            this.titleLevelLabel.string = text;
+        }
+    }
+
+    private _applyNextButtonText(): void {
+        if (!this.nextLevelButton || this._nextButtonText === null) {
+            return;
+        }
+
+        const label = this.nextLevelButton.getChildByName('Label')?.getComponent(Label);
+        if (label) {
+            label.string = this._nextButtonText;
+        }
+    }
+
+    private _applyProgressText(text: string | undefined): void {
+        if (this.progressLabel && text !== undefined) {
+            this.progressLabel.string = text;
+        }
+    }
+
+    private _applyProgressValue(progress: number | undefined): void {
+        if (progress === undefined) {
+            return;
+        }
+
+        this._applyAnimatedProgress(progress);
+    }
+
+    /**
+     * 根据 _previousTitleInfo → _titleInfo 驱动进度条过渡动画
+     *
+     * 三种情况：
+     * 1. 无起点信息或起点/终点相同：不播动画
+     * 2. 同称号下涨进度：一段 tween
+     * 3. 跨称号：先把旧称号填到 1.0，然后切换称号文字、进度回 0，再 tween 到终点进度
+     */
+    private _playProgressAnimation(): void {
+        const prev = this._previousTitleInfo;
+        // 动画是一次性的，播放前消费掉，避免弹窗被复用时重复播
+        this._previousTitleInfo = null;
+
+        if (!this.titleProgressBar || !prev) {
+            return;
+        }
+
+        const startProgress = prev.nextTitleProgress;
+        const endProgress = this._titleInfo.nextTitleProgress;
+        if (startProgress === undefined || endProgress === undefined) {
+            return;
+        }
+
+        const isSameTitle = prev.titleText === undefined
+            || this._titleInfo.titleText === undefined
+            || prev.titleText === this._titleInfo.titleText;
+
+        // 同称号且起止相同，没必要播动画
+        if (isSameTitle && Math.abs(startProgress - endProgress) < 1e-4) {
+            return;
+        }
+
+        this._stopProgressAnimation();
+
+        if (isSameTitle) {
+            // 先展示起点，避免 _refreshTitleView 已把条填到终态
+            this._applyProgressValue(startProgress);
+            this._runProgressTween(startProgress, endProgress, PassModal.PROGRESS_ANIM_START_DELAY);
+            return;
+        }
+
+        // 跨称号：先让旧称号文字和起点进度出现在屏上
+        this._applyTitleText(prev.titleText);
+        this._applyProgressText(prev.progressText);
+        this._applyProgressValue(startProgress);
+
+        const self = this;
+        const tweenTarget = this._progressTweenTarget;
+        // raw 值保留 0~1；下发时经 _normalizeProgress
+        tweenTarget.progress = Math.max(0, Math.min(1, startProgress));
+        const clampedEnd = Math.max(0, Math.min(1, endProgress));
+
+        const onUpdate = () => {
+            self._applyAnimatedProgress(tweenTarget.progress);
+        };
+
+        tween(tweenTarget)
+            .delay(PassModal.PROGRESS_ANIM_START_DELAY)
+            .to(
+                PassModal.PROGRESS_ANIM_SEGMENT_DURATION,
+                { progress: 1 },
+                { easing: 'sineOut', onUpdate }
+            )
+            .call(() => {
+                // 切到新称号。progressText/titleText 都切到终态；进度值从 0 开始
+                self._applyTitleText(self._titleInfo.titleText);
+                self._applyProgressText(self._titleInfo.progressText);
+                tweenTarget.progress = 0;
+                self._applyAnimatedProgress(0);
+            })
+            .delay(PassModal.PROGRESS_ANIM_LEVELUP_PAUSE)
+            .to(
+                PassModal.PROGRESS_ANIM_SEGMENT_DURATION,
+                { progress: clampedEnd },
+                { easing: 'sineOut', onUpdate }
+            )
+            .start();
+    }
+
+    private _runProgressTween(from: number, to: number, delay: number): void {
+        if (!this.titleProgressBar) {
+            return;
+        }
+
+        const tweenTarget = this._progressTweenTarget;
+        // raw 值保留 0~1 区间，onUpdate 里经 _normalizeProgress 再下发，避免畸变区段
+        tweenTarget.progress = this._clampProgress(from);
+        this._applyAnimatedProgress(from);
+
+        const self = this;
+        const chain = tween(tweenTarget);
+        if (delay > 0) {
+            chain.delay(delay);
+        }
+
+        chain
+            .to(
+                PassModal.PROGRESS_ANIM_SEGMENT_DURATION,
+                { progress: Math.max(0, Math.min(1, to)) },
+                {
+                    easing: 'sineOut',
+                    onUpdate: () => {
+                        self._applyAnimatedProgress(tweenTarget.progress);
+                    }
+                }
+            )
+            .start();
+    }
+
+    private _cacheProgressAnchorStartX(): void {
+        if (this._progressAnchorStartX !== null || !this.titleProgressBar) {
+            return;
+        }
+
+        const barSprite = this.titleProgressBar.barSprite;
+        if (!barSprite) {
+            return;
+        }
+
+        // Bar 节点 anchor 为 (0, 0.5)，其本地 position.x 即为进度条可视左端。
+        // ProgressBar 与 ProgressAnchor 共享同一父节点（TitleLevel），
+        // 因此把 Bar 的本地 X 按 ProgressBar 自身的位移与缩放映射到父节点空间，
+        // 才是真正的「0% 起点」。直接拿 progressAnchor.position.x 当起点会导致
+        // 气泡始终被 prefab 摆放偏移量带跑（实测偏右 ~24px）。
+        // -40 为视觉微调，与 PageHome 保持一致。
+        const progressBarNode = this.titleProgressBar.node;
+        const barLocalX = barSprite.node.position.x;
+        this._progressAnchorStartX = progressBarNode.position.x + barLocalX * progressBarNode.scale.x - 30;
+    }
+
+    private _resolveProgressAnchor(): void {
+        if (this.progressAnchor?.isValid) {
+            return;
+        }
+
+        this.progressAnchor = this.node
+            .getChildByName('Bg')
+            ?.getChildByName('Title')
+            ?.getChildByName('ProgressAnchor') ?? null;
+    }
+
+    private _applyAnimatedProgress(progress: number): void {
+        const clampedProgress = this._clampProgress(progress);
+
+        if (this.titleProgressBar?.isValid) {
+            this.titleProgressBar.progress = this._normalizeProgress(clampedProgress);
+        }
+
+        this._updateProgressAnchor(clampedProgress);
+    }
+
+    private _updateProgressAnchor(progress: number): void {
+        if (!this.progressAnchor?.isValid) {
+            return;
+        }
+
+        this._cacheProgressAnchorStartX();
+
+        const startX = this._progressAnchorStartX ?? this.progressAnchor.position.x;
+        const travelWidth = this._getProgressAnchorTravelWidth();
+        this.progressAnchor.setPosition(startX + travelWidth * progress, this.progressAnchor.position.y, this.progressAnchor.position.z);
+
+        const percentLabel = this.progressAnchor.getChildByName('Label')?.getComponent(Label);
+        if (percentLabel) {
+            percentLabel.string = `${Math.round(progress * 100)}%`;
+        }
+    }
+
+    private _getProgressAnchorTravelWidth(): number {
+        if (!this.titleProgressBar) {
+            return 0;
+        }
+
+        return Math.abs(this.titleProgressBar.totalLength * this.titleProgressBar.node.scale.x);
+    }
+
+    private _stopProgressAnimation(): void {
+        Tween.stopAllByTarget(this._progressTweenTarget);
+    }
+
+    /**
+     * 规范化进度值
+     * 九宫格 Bar 的 Left+Right border = 240px，totalLength = 925px
+     * 当 width < 240px 时圆角会畸变，因此 progress > 0 时强制最小值
+     */
+    private _normalizeProgress(progress: number): number {
+        if (!Number.isFinite(progress) || progress <= 0) {
+            return 0;
+        }
+
+        const MIN_PROGRESS = 240 / 925;
+        return Math.max(MIN_PROGRESS, Math.min(1, progress));
+    }
+
+    private _clampProgress(progress: number): number {
+        if (!Number.isFinite(progress) || progress <= 0) {
+            return 0;
+        }
+
+        return Math.min(1, progress);
+    }
+
+    /**
+     * 下一关按钮点击
+     */
+    private _onNextLevelClick(): void {
+        console.log('[PassModal] 点击下一关');
+        this._callbacks.onNextLevel?.();
+    }
+
+    /**
+     * 分享按钮点击
+     */
+    private _onShareClick(): void {
+        console.log('[PassModal] 点击分享');
+
+        // 调用微信分享
+        WxSDK.shareAppMessage({
+            title: '快来一起玩这款游戏吧',
+            query: `level=${this._params?.levelIndex ?? 1}`
+        });
+
+        this._callbacks.onShare?.();
+    }
+
+    /**
+     * 返回主页按钮点击
+     */
+    private _onHomeClick(): void {
+        console.log('[PassModal] 点击返回主页');
+        AudioManager.instance.playButtonClick();
+        this._callbacks.onHome?.();
+    }
+}
+```
+
+### 8.2 预览关卡项 (assets/prefabs/PreviewLevelItem.ts)
+
+```typescript
+import { _decorator, Component, Node, Sprite, Label, SpriteFrame } from 'cc';
+const { ccclass, property } = _decorator;
+
+/**
+ * 预览页单个关卡 item 的视图组件
+ * 挂在 PagePreviewLevels 的 listTemplate 根节点上，由编辑器拖拽绑定子节点。
+ * instantiate 克隆 item 时，Cocos 会把这些 Node 引用自动重映射到克隆后的子节点，
+ * 所以每个 item 拿到的都是自己的封面/标签引用，与节点层级/命名解耦。
+ */
+@ccclass('PreviewLevelItem')
+export class PreviewLevelItem extends Component {
+    @property({ type: Sprite, tooltip: '封面图 Sprite' })
+    levelCover: Sprite | null = null;
+
+    @property({ type: Label, tooltip: '答案 Label' })
+    answerLabel: Label | null = null;
+
+    @property({ type: Label, tooltip: '线索1 Label' })
+    tips1Label: Label | null = null;
+
+    @property({ type: Label, tooltip: '线索2 Label' })
+    tips2Label: Label | null = null;
+
+    @property({ type: Label, tooltip: '线索3 Label' })
+    tips3Label: Label | null = null;
+
+    /**
+     * 一次性设置所有文本字段
+     */
+    setTexts(opts: {
+        answer: string;
+        hint1: string;
+        hint2: string;
+        hint3: string;
+    }): void {
+        if (this.answerLabel) this.answerLabel.string = `答案：${opts.answer}`;
+        if (this.tips1Label) this.tips1Label.string = opts.hint1;
+        if (this.tips2Label) this.tips2Label.string = opts.hint2;
+        if (this.tips3Label) this.tips3Label.string = opts.hint3;
+    }
+
+    setCover(spriteFrame: SpriteFrame | null): void {
+        if (this.levelCover && spriteFrame) {
+            this.levelCover.spriteFrame = spriteFrame;
+        }
+    }
+}
+```
+
+### 8.3 Toast 组件 (assets/prefabs/Toast.ts)
+
+```typescript
+import { _decorator, Component, Label, tween, UIOpacity } from 'cc';
+const { ccclass, property } = _decorator;
+
+@ccclass('Toast')
+export class Toast extends Component {
+    @property(Label)
+    contentLabel: Label | null = null;
+
+    private _uiOpacity: UIOpacity | null = null;
+
+    onLoad() {
+        // 获取或添加 UIOpacity 组件用于透明度动画
+        this._uiOpacity = this.node.getComponent(UIOpacity);
+        if (!this._uiOpacity) {
+            this._uiOpacity = this.node.addComponent(UIOpacity);
+        }
+    }
+
+    /**
+     * 显示 Toast
+     * @param content 提示内容
+     * @param duration 显示时长（毫秒），默认 2000ms
+     */
+    show(content: string, duration: number = 2000): void {
+        if (this.contentLabel) {
+            this.contentLabel.string = content;
+        }
+
+        // 重置透明度
+        this._uiOpacity!.opacity = 255;
+
+        // 延迟后执行渐隐动画
+        this.scheduleOnce(() => {
+            this._fadeOut();
+        }, duration / 1000);
+    }
+
+    /**
+     * 渐隐动画并销毁
+     */
+    private _fadeOut(): void {
+        tween(this._uiOpacity!)
+            .to(0.3, { opacity: 0 })
+            .call(() => {
+                this.node.destroy();
+            })
+            .start();
+    }
+}
+```
+
+### 8.4 Toast 管理器 (assets/scripts/utils/ToastManager.ts)
+
+```typescript
+import { Node, Prefab, instantiate, find } from 'cc';
+
+/**
+ * Toast 管理器
+ * 单例模式，统一管理 Toast 提示的显示
+ */
+export class ToastManager {
+    private static _instance: ToastManager | null = null;
+    private _prefab: Prefab | null = null;
+    private _container: Node | null = null;
+
+    static get instance(): ToastManager {
+        if (!this._instance) {
+            this._instance = new ToastManager();
+        }
+        return this._instance;
+    }
+
+    private constructor() {}
+
+    /**
+     * 初始化 Toast 管理器
+     * @param prefab Toast 预制体
+     * @param container Toast 容器节点（默认为 Canvas）
+     */
+    init(prefab: Prefab, container?: Node): void {
+        this._prefab = prefab;
+        this._container = container ?? find('Canvas');
+    }
+
+    /**
+     * 显示 Toast 提示
+     * @param content 提示内容
+     * @param duration 显示时长（毫秒），默认 2000ms
+     */
+    show(content: string, duration: number = 2000): void {
+        if (!this._prefab || !this._container) {
+            console.error('[ToastManager] 未初始化，请先调用 init()');
+            return;
+        }
+
+        const node = instantiate(this._prefab);
+        this._container.addChild(node);
+
+        // 动态获取 Toast 组件
+        const toast = node.getComponent('Toast') as any;
+        if (toast && typeof toast.show === 'function') {
+            toast.show(content, duration);
+        }
+    }
+
+    /**
+     * 静态快捷方法
+     */
+    static show(content: string, duration: number = 2000): void {
+        ToastManager.instance.show(content, duration);
+    }
+}
+```