《Cocos 游戏联机实战》9.2 网络状态 UI 与提示

// sync/net-quality.ts —— 纯 TS，网络质量档位与展示映射
export type NetTier = 'good' | 'fair' | 'poor' | 'offline';

export interface NetMetrics {
  rttMs: number; // 已平滑的往返延迟
  lossPct: number; // 已平滑的丢包率，0~100
  connected: boolean;
}

export interface TierDisplay {
  bars: number; // 信号格 0~3
  label: string; // zh-CN 兜底文案，生产环境替换为 i18n key
}

/** 把平滑后的指标映射到四档。边界取 >=，档位越低越差。 */
export function classify(m: NetMetrics): NetTier {
  if (!m.connected) return 'offline';
  if (m.rttMs >= 300 || m.lossPct >= 5) return 'poor';
  if (m.rttMs >= 150 || m.lossPct >= 1) return 'fair';
  return 'good';
}

const DISPLAY: Record<NetTier, TierDisplay> = {
  good: { bars: 3, label: '网络良好' },
  fair: { bars: 2, label: '网络一般' },
  poor: { bars: 1, label: '网络较差' },
  offline: { bars: 0, label: '连接已断开' },
};

export function describe(tier: NetTier): TierDisplay {
  return DISPLAY[tier];
}

/** 是否值得给玩家弹一次提示：抑制抖动，只在有意义的变化上打扰。 */
export function shouldNotify(prev: NetTier, next: NetTier): boolean {
  if (prev === next) return false;
  if (next === 'poor' || next === 'offline') return true; // 恶化，立刻提示
  if (prev === 'poor' || prev === 'offline') return next === 'good'; // 恢复，只提示彻底好转
  return false; // good 与 fair 之间不打扰
}

import { describe, expect, it } from 'vitest';
import { classify, describe, shouldNotify, type NetMetrics } from './net-quality';

const m = (rttMs: number, lossPct: number, connected = true): NetMetrics =>
  ({ rttMs, lossPct, connected });

describe('classify 档位边界', () => {
  it('rtt 恰好 150 进 fair，149 仍是 good', () => {
    expect(classify(m(149, 0))).toBe('good');
    expect(classify(m(150, 0))).toBe('fair');
  });

  it('rtt 恰好 300 进 poor', () => {
    expect(classify(m(299, 0))).toBe('fair');
    expect(classify(m(300, 0))).toBe('poor');
  });

  it('丢包边界 1% 与 5%', () => {
    expect(classify(m(0, 0.9))).toBe('good');
    expect(classify(m(0, 1))).toBe('fair');
    expect(classify(m(0, 5))).toBe('poor');
  });

  it('断连优先于一切指标', () => {
    expect(classify(m(0, 0, false))).toBe('offline');
  });
});

describe('describe 映射', () => {
  it('档位越差格数越少', () => {
    expect(describe('good').bars).toBe(3);
    expect(describe('fair').bars).toBe(2);
    expect(describe('poor').bars).toBe(1);
    expect(describe('offline').bars).toBe(0);
  });
});

describe('shouldNotify 抑制抖动', () => {
  it('good 与 fair 之间不打扰', () => {
    expect(shouldNotify('good', 'fair')).toBe(false);
    expect(shouldNotify('fair', 'good')).toBe(false);
  });

  it('恶化到 poor / offline 立即提示', () => {
    expect(shouldNotify('good', 'poor')).toBe(true);
    expect(shouldNotify('fair', 'offline')).toBe(true);
  });

  it('恢复只在彻底好转时提示', () => {
    expect(shouldNotify('poor', 'good')).toBe(true);
    expect(shouldNotify('poor', 'fair')).toBe(false);
  });
});

// assets/scripts/net/ui/NetStatusView.ts
import { _decorator, Color, Component, Label, ProgressBar, Sprite, UIOpacity } from 'cc';
import { classify, describe, shouldNotify, type NetMetrics, type NetTier } from '../sync/net-quality';

const { ccclass, property } = _decorator;

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

  @property(Sprite)
  signal: Sprite | null = null;

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

  @property(UIOpacity)
  reconnectGroup: UIOpacity | null = null;

  @property
  reconnectSeconds = 8;

  private tier: NetTier = 'good';
  private metrics: NetMetrics = { rttMs: 0, lossPct: 0, connected: true };
  private reconnectLeft = 0;

  /** 会话层 / 诊断层推送最新指标。 */
  onMetrics(m: NetMetrics): void {
    this.metrics = m;
  }

  /** 重连开始或结束时调用（第 5.1 节的重连状态机回调）。 */
  onReconnect(active: boolean): void {
    this.reconnectLeft = active ? this.reconnectSeconds : 0;
  }

  update(dt: number): void {
    if (this.reconnectLeft > 0) this.reconnectLeft = Math.max(0, this.reconnectLeft - dt);
    const next = classify(this.metrics);
    if (next !== this.tier) {
      if (shouldNotify(this.tier, next)) this.notify(next);
      this.tier = next;
    }
    this.refresh(next);
  }

  private notify(tier: NetTier): void {
    console.log('网络提示：', describe(tier).label);
  }

  private refresh(tier: NetTier): void {
    const d = describe(tier);
    if (this.text) this.text.string = d.label;
    if (this.signal) this.signal.color = this.tierColor(tier);
    if (this.reconnectGroup) this.reconnectGroup.opacity = this.reconnectLeft > 0 ? 255 : 0;
    if (this.reconnectBar) this.reconnectBar.progress = this.reconnectSeconds > 0 ? this.reconnectLeft / this.reconnectSeconds : 0;
  }

  private tierColor(tier: NetTier): Color {
    if (tier === 'good') return new Color(120, 200, 120, 255);
    if (tier === 'fair') return new Color(230, 200, 90, 255);
    if (tier === 'poor') return new Color(220, 120, 80, 255);
    return new Color(160, 160, 160, 255);
  }
}

import { sys } from 'cc';

// 微信小游戏切后台会被系统断连，重连提示要更醒目；H5 走 visibilitychange。
export function reconnectHintLevel(): 'loud' | 'normal' {
  return sys.platform === sys.Platform.WECHAT_GAME ? 'loud' : 'normal';
}