《Cocos 游戏开发实战》6.3 弹窗栈与多语言

// 反面教材：状态散落在各处，很快失控
if (!settingsPanel.isOpen && !pausePanel.isOpen && !resultPanel.isOpen) {
  openDailyReward();
}

// src/ui/popup-base.ts —— 所有弹窗的基类
import {
  _decorator, Component, UIOpacity, BlockInputEvents, tween, Vec3,
} from 'cc';
const { ccclass } = _decorator;

@ccclass('PopupBase')
export class PopupBase extends Component {
  protected blocker: BlockInputEvents | null = null;
  protected opacity: UIOpacity | null = null;

  onLoad(): void {
    this.opacity = this.node.getComponent(UIOpacity) ?? this.node.addComponent(UIOpacity);
    // 弹窗出现即拦截输入，避免点穿到下层界面
    this.blocker = this.node.getComponent(BlockInputEvents) ?? this.node.addComponent(BlockInputEvents);
    this.node.setScale(0.85, 0.85, 1);
    this.opacity.opacity = 0;
  }

  /** 打开动画：0.18 秒淡入并放大到原尺寸 */
  open(done?: () => void): void {
    const op = this.opacity;
    if (op === null) return;
    tween(op).to(0.18, { opacity: 255 }).start();
    tween(this.node)
      .to(0.18, { scale: new Vec3(1, 1, 1) }, { easing: 'backOut' })
      .call(() => done?.())
      .start();
  }

  /** 关闭动画：淡出并缩小，结束后从父节点摘除 */
  close(done?: () => void): void {
    const op = this.opacity;
    if (op === null) return;
    tween(op).to(0.14, { opacity: 0 }).start();
    tween(this.node)
      .to(0.14, { scale: new Vec3(0.85, 0.85, 1) })
      .call(() => {
        done?.();
        this.node.removeFromParent();
      })
      .start();
  }
}

// src/core/popup-stack.ts —— 与引擎无关，可直接单测
export class PopupStack {
  private readonly stack: string[] = [];
  private readonly maxDepth: number;

  constructor(maxDepth = 4) {
    this.maxDepth = maxDepth;
  }

  /** 压入一个弹窗名；超过上限或重复压入返回 false */
  push(name: string): boolean {
    if (this.stack.length >= this.maxDepth) return false;
    if (this.stack.includes(name)) return false;
    this.stack.push(name);
    return true;
  }

  /** 弹出栈顶；可指定必须匹配的名字，防止动画错位时误关 */
  pop(name?: string): string | null {
    const top = this.stack[this.stack.length - 1];
    if (top === undefined) return null;
    if (name !== undefined && name !== top) return null;
    this.stack.pop();
    return top;
  }

  get top(): string | null {
    return this.stack[this.stack.length - 1] ?? null;
  }

  get depth(): number {
    return this.stack.length;
  }

  has(name: string): boolean {
    return this.stack.includes(name);
  }
}

// tests/popup-stack.test.ts
import { describe, it, expect } from 'vitest';
import { PopupStack } from '../src/core/popup-stack';

describe('PopupStack', () => {
  it('重复压入同名弹窗被拒绝', () => {
    const s = new PopupStack();
    expect(s.push('pause')).toBe(true);
    expect(s.push('pause')).toBe(false);
    expect(s.depth).toBe(1);
  });

  it('指定名字不匹配时拒绝弹出', () => {
    const s = new PopupStack();
    s.push('pause');
    s.push('confirm');
    expect(s.pop('pause')).toBeNull();
    expect(s.top).toBe('confirm');
    expect(s.pop('confirm')).toBe('confirm');
    expect(s.top).toBe('pause');
  });
});

// src/ui/popup-manager.ts —— 挂在 PopupLayer 上
import { _decorator, Component, Node, Prefab, instantiate } from 'cc';
import { PopupStack } from '../core/popup-stack';
const { ccclass, property } = _decorator;

/** 只声明管理器真正用到的两个方法，避免和弹窗基类强耦合 */
interface PopupLike {
  open(done?: () => void): void;
  close(done?: () => void): void;
}

@ccclass('PopupManager')
export class PopupManager extends Component {
  @property(Prefab) pausePrefab: Prefab | null = null;
  @property(Prefab) resultPrefab: Prefab | null = null;

  private stack = new PopupStack(4);

  private registry: Record<string, Prefab | null> = {};

  onLoad(): void {
    this.registry = { pause: this.pausePrefab, result: this.resultPrefab };
  }

  show(name: string): boolean {
    if (!this.stack.push(name)) return false;
    const prefab = this.registry[name] ?? null;
    if (prefab === null) return false;
    const node: Node = instantiate(prefab);
    this.node.addChild(node);
    const popup = node.getComponent('PopupBase') as unknown as PopupLike | null;
    popup?.open();
    return true;
  }

  dismiss(): void {
    const name: string | null = this.stack.top;
    if (name === null) return;
    const top = this.node.getChildByName(name);
    const popup = top?.getComponent('PopupBase') as unknown as PopupLike | null;
    popup?.close(() => { this.stack.pop(name); });
  }
}

// src/core/i18n.ts —— 与引擎无关，可直接单测
export type Lang = 'zh' | 'en';

const TABLES: Record<Lang, Record<string, string>> = {
  zh: {
    'hud.coins': '金币',
    'popup.pause': '暂停',
    'popup.resume': '继续',
    'popup.result.win': '通关！',
    'popup.result.lose': '再来一次',
  },
  en: {
    'hud.coins': 'Coins',
    'popup.pause': 'Paused',
    'popup.resume': 'Resume',
    'popup.result.win': 'Level Clear!',
    'popup.result.lose': 'Try Again',
  },
};

/** 从平台上报的 languageCode 归一到受支持的语言 */
export function normalizeLang(code: string): Lang {
  return code.toLowerCase().startsWith('zh') ? 'zh' : 'en';
}

export class I18n {
  private lang: Lang;
  private readonly fallback: Lang;

  constructor(lang: Lang, fallback: Lang = 'zh') {
    this.lang = lang;
    this.fallback = fallback;
  }

  setLang(lang: Lang): void {
    this.lang = lang;
  }

  /** 取文案；当前语言缺 key 时退回 fallback，再缺则原样返回 key */
  t(key: string): string {
    const cur = TABLES[this.lang][key];
    if (cur !== undefined) return cur;
    return TABLES[this.fallback][key] ?? key;
  }
}

import { _decorator, Component, Label, sys } from 'cc';
import { I18n, normalizeLang, Lang } from '../core/i18n';
const { ccclass, property } = _decorator;

@ccclass('I18nBinder')
export class I18nBinder extends Component {
  @property(Label) coinsLabel: Label | null = null;

  private i18n: I18n = new I18n('zh');

  onLoad(): void {
    const lang: Lang = normalizeLang(sys.languageCode);
    this.i18n = new I18n(lang);
    this.refresh();
  }

  refresh(): void {
    if (this.coinsLabel !== null) {
      this.coinsLabel.string = this.i18n.t('hud.coins');
    }
  }

  switchTo(lang: Lang): void {
    this.i18n.setLang(lang);
    this.refresh();
  }
}