《Cocos 游戏开发入门》11.3 弹窗栈与界面状态机

// src/ui/popup-stack.ts
export interface PopupDef {
  /** 弹窗唯一标识，如 'pause'、'settings'、'confirm-quit' */
  id: string;
  /** 是否绘制全屏遮罩 */
  modal: boolean;
  /** 点击遮罩是否关闭本弹窗 */
  dismissOnMask: boolean;
}

export interface PopupInstance extends PopupDef {
  /** 同一 id 可能被 push 多次，用序号区分实例 */
  seq: number;
}

export class PopupStack {
  private items: PopupInstance[] = [];
  private nextSeq = 1;

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

  /** 只读快照，供命中测试等外部逻辑遍历 */
  snapshot(): readonly PopupInstance[] {
    return this.items;
  }

  top(): PopupInstance | null {
    return this.items.length > 0 ? this.items[this.items.length - 1] : null;
  }

  push(def: PopupDef): PopupInstance {
    const inst: PopupInstance = { ...def, seq: this.nextSeq };
    this.nextSeq += 1;
    this.items.push(inst);
    return inst;
  }

  pop(): PopupInstance | null {
    return this.items.pop() ?? null;
  }

  /** 用新弹窗替换栈顶：栈深不变，适合同级页面切换 */
  replace(def: PopupDef): PopupInstance {
    this.items.pop();
    return this.push(def);
  }

  /** 关掉栈顶以下的所有弹窗，只留最底一层 */
  popToRoot(): void {
    if (this.items.length > 1) this.items.length = 1;
  }

  has(id: string): boolean {
    return this.items.some((it) => it.id === id);
  }
}

export interface HitResult {
  target: PopupInstance | null;
  blocked: boolean;
}

/**
 * 路由一次点击。hitTest 判断某层是否命中坐标。
 * 从栈顶向下遍历，遇到 modal 层且未命中即阻断。
 */
export function routePointer(
  stack: PopupStack,
  hitTest: (inst: PopupInstance, x: number, y: number) => boolean,
  x: number,
  y: number,
): HitResult {
  const items = stack.snapshot();
  for (let i = items.length - 1; i >= 0; i -= 1) {
    const inst = items[i];
    if (hitTest(inst, x, y)) return { target: inst, blocked: false };
    if (inst.modal) return { target: null, blocked: true };
  }
  return { target: null, blocked: false };
}

// src/ui/screen-machine.ts
export type ScreenId = 'boot' | 'menu' | 'playing' | 'paused' | 'result';

/** 允许的跳转表：从 key 只能到 value 中列出的屏幕 */
const TRANSITIONS: Record<ScreenId, readonly ScreenId[]> = {
  boot: ['menu'],
  menu: ['playing'],
  playing: ['paused', 'result'],
  paused: ['playing', 'menu'],
  result: ['menu', 'playing'],
};

export class ScreenMachine {
  private current: ScreenId = 'boot';

  get state(): ScreenId {
    return this.current;
  }

  canGo(to: ScreenId): boolean {
    return TRANSITIONS[this.current].includes(to);
  }

  /** 合法则跳转并返回 true，否则保持原状返回 false */
  go(to: ScreenId): boolean {
    if (!this.canGo(to)) return false;
    this.current = to;
    return true;
  }
}

/**
 * 统一处理返回键。返回 true 表示事件已被消费，不再向上传递。
 * 优先级：栈顶弹窗 > 屏幕回退。
 */
export function handleBack(
  stack: PopupStack,
  machine: ScreenMachine,
): boolean {
  if (stack.top() !== null) {
    stack.pop();
    return true;
  }
  if (machine.state === 'paused') return machine.go('menu');
  if (machine.state === 'playing') return machine.go('paused');
  return false;
}

// tests/popup-stack.test.ts
import { describe, it, expect } from 'vitest';
import { PopupStack, routePointer } from '../src/ui/popup-stack';
import { ScreenMachine, handleBack } from '../src/ui/screen-machine';

const modalPopup = { id: 'pause', modal: true, dismissOnMask: false };

describe('popup-stack', () => {
  it('push/pop 维持后进先出', () => {
    const s = new PopupStack();
    s.push(modalPopup);
    s.push({ id: 'settings', modal: true, dismissOnMask: false });
    expect(s.depth).toBe(2);
    expect(s.top()?.id).toBe('settings');
    expect(s.pop()?.id).toBe('settings');
    expect(s.top()?.id).toBe('pause');
  });

  it('模态弹窗阻断下层点击', () => {
    const s = new PopupStack();
    s.push(modalPopup);
    const r = routePointer(s, () => false, 10, 10);
    expect(r.target).toBeNull();
    expect(r.blocked).toBe(true);
  });

  it('非模态弹窗不阻断下层点击', () => {
    const s = new PopupStack();
    s.push({ id: 'toast', modal: false, dismissOnMask: false });
    const r = routePointer(s, () => false, 10, 10);
    expect(r.blocked).toBe(false);
  });

  it('状态机拒绝非法跳转', () => {
    const m = new ScreenMachine();
    expect(m.go('playing')).toBe(false); // boot → playing 非法
    expect(m.go('menu')).toBe(true);
    expect(m.go('playing')).toBe(true);
    expect(m.state).toBe('playing');
  });

  it('返回键先关弹窗再回退屏幕', () => {
    const s = new PopupStack();
    const m = new ScreenMachine();
    m.go('menu');
    m.go('playing');
    s.push(modalPopup);
    expect(handleBack(s, m)).toBe(true);
    expect(s.depth).toBe(0);
    expect(m.state).toBe('playing');
    expect(handleBack(s, m)).toBe(true);
    expect(m.state).toBe('paused');
  });
});

import { _decorator, Component, Node, BlockInputEvents, input, Input, KeyCode, EventKeyboard } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('PopupHost')
export class PopupHost extends Component {
  @property(Node)
  pausePanel: Node | null = null;

  onEnable(): void {
    input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this);
  }

  onDisable(): void {
    input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this);
  }

  private onKeyDown(event: EventKeyboard): void {
    if (event.keyCode !== KeyCode.ESCAPE && event.keyCode !== KeyCode.MOBILE_BACK) {
      return;
    }
    this.closeTopPopup();
  }

  openPause(): void {
    const panel = this.pausePanel;
    if (panel === null) return;
    panel.active = true;
    // 挂上后，落在面板矩形内的触摸不再传给下层
    panel.addComponent(BlockInputEvents);
  }

  closeTopPopup(): void {
    const panel = this.pausePanel;
    if (panel === null) return;
    panel.active = false;
  }
}