《Cocos 游戏开发入门》9.3 移动端音频限制与解锁

// mini2d/audio/unlock.ts
export class AudioUnlocker {
  private unlocked = false;
  private pending: Array<() => void> = [];

  get isUnlocked(): boolean {
    return this.unlocked;
  }

  /** 注册一次待解锁后要执行的动作（例如补播 BGM） */
  whenUnlocked(fn: () => void): void {
    if (this.unlocked) fn();
    else this.pending.push(fn);
  }

  /** 在首次真实用户手势里调用 */
  unlock(): void {
    if (this.unlocked) return;
    this.unlocked = true;
    for (const fn of this.pending) fn();
    this.pending = [];
  }
}

export async function safePlay(
  el: HTMLAudioElement,
  unlocker: AudioUnlocker,
  retry: () => void,
): Promise<void> {
  try {
    await el.play();
  } catch (err) {
    // 自动播放被拦截：记下来，等用户交互后重试
    unlocker.whenUnlocked(retry);
  }
}

export function installUnlockListeners(unlocker: AudioUnlocker): void {
  const events: Array<keyof WindowEventMap> = ['pointerdown', 'touchend', 'keydown'];
  const handler = (): void => {
    unlocker.unlock();
    for (const e of events) window.removeEventListener(e, handler);
  };
  for (const e of events) window.addEventListener(e, handler, { passive: true });
}

// mini2d/audio/context.ts
let ctx: AudioContext | null = null;

export function getAudioContext(): AudioContext {
  if (!ctx) ctx = new AudioContext();
  return ctx;
}

export async function resumeAudioContext(): Promise<void> {
  const c = getAudioContext();
  if (c.state === 'suspended') {
    await c.resume(); // 同样必须在用户手势回调里调用
  }
}

// mini2d/audio/lifecycle.ts
import type { AudioUnlocker } from './unlock';

export function installVisibilityHandler(
  pauseAll: () => void,
  resumeAll: () => void,
): void {
  document.addEventListener('visibilitychange', () => {
    if (document.hidden) {
      pauseAll(); // 切到后台：停掉 BGM 与所有音效，省电
    } else {
      resumeAll(); // 回前台：恢复 BGM（音效不补播）
    }
  });
}

// 在《方块冲刺》里接线
const unlocker = new AudioUnlocker();
installUnlockListeners(unlocker);
installVisibilityHandler(
  () => bgm.pause(),
  () => bgm.resume(), // 内部：若未解锁则挂到 unlocker，否则直接 play
);

// 启动时
const unlocker = new AudioUnlocker();
installUnlockListeners(unlocker);
installVisibilityHandler(() => bgm.pause(), () => bgm.resume());

// 需要播放时，一律走 whenUnlocked 包装
unlocker.whenUnlocked(() => bgm.play('level_run'));

import { _decorator, Component, game, Game, sys, AudioSource } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('AudioLifecycle')
export class AudioLifecycle extends Component {
  @property(AudioSource)
  bgm: AudioSource | null = null;

  onLoad(): void {
    game.on(Game.EVENT_HIDE, this.onHide, this);
    game.on(Game.EVENT_SHOW, this.onShow, this);
  }

  onDestroy(): void {
    game.off(Game.EVENT_HIDE, this.onHide, this);
    game.off(Game.EVENT_SHOW, this.onShow, this);
  }

  private onHide(): void {
    this.bgm?.pause();
  }

  private onShow(): void {
    if (sys.isMobile) {
      this.bgm?.play(); // 移动端回前台需显式恢复
    } else {
      this.bgm?.play();
    }
  }
}