《Cocos 游戏开发实战》6.1 UI 层级与多分辨率适配

{
  "__type__": "cc.Node",
  "_name": "Canvas",
  "_components": [ { "__id__": 3 }, { "__id__": 4 }, { "__id__": 5 } ],
  "_children": [
    { "__id__": 6 },
    { "__id__": 10 },
    { "__id__": 14 }
  ]
}

{
  "__type__": "cc.Settings",
  "general": {
    "designResolution": {
      "width": 960,
      "height": 540,
      "fitWidth": true,
      "fitHeight": true
    }
  }
}

import { _decorator, Component, view, ResolutionPolicy } from 'cc';
const { ccclass } = _decorator;

@ccclass('ResolutionBootstrap')
export class ResolutionBootstrap extends Component {
  start(): void {
    view.setDesignResolutionSize(960, 540, ResolutionPolicy.SHOW_ALL);
    const visible = view.getVisibleSize();
    console.log('[ResolutionBootstrap] 可见尺寸', visible.width, visible.height);
    console.log('[ResolutionBootstrap] 缩放', view.getScaleX(), view.getScaleY());
  }
}

import { _decorator, Component, Node, Widget } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('HudAnchors')
export class HudAnchors extends Component {
  @property(Node) coinLabel: Node | null = null;
  @property(Node) pauseButton: Node | null = null;

  start(): void {
    this.anchor(this.coinLabel, { top: 16, left: 24 });
    this.anchor(this.pauseButton, { top: 16, right: 24 });
  }

  private anchor(
    node: Node | null,
    edge: { top?: number; left?: number; right?: number; bottom?: number },
  ): void {
    if (node === null) return;
    const w = node.getComponent(Widget) ?? node.addComponent(Widget);
    if (edge.top !== undefined) { w.isAlignTop = true; w.top = edge.top; }
    if (edge.bottom !== undefined) { w.isAlignBottom = true; w.bottom = edge.bottom; }
    if (edge.left !== undefined) { w.isAlignLeft = true; w.left = edge.left; }
    if (edge.right !== undefined) { w.isAlignRight = true; w.right = edge.right; }
    w.alignMode = Widget.AlignMode.ON_WINDOW_RESIZE;
    w.updateAlignment();
  }
}

import { _decorator, Component, view, screen, sys } from 'cc';
const { ccclass } = _decorator;

@ccclass('SafeAreaProbe')
export class SafeAreaProbe extends Component {
  start(): void {
    const frame = view.getFrameSize();
    const pixel = view.getVisibleSizeInPixel();
    console.log('[SafeAreaProbe] 帧尺寸', frame.width, frame.height);
    console.log('[SafeAreaProbe] 像素可见', pixel.width, pixel.height);
    console.log('[SafeAreaProbe] 设备像素比', screen.devicePixelRatio);
    if (sys.isMobile && sys.platform === sys.Platform.WECHAT_GAME) {
      // 小游戏端的安全区由平台接口给出，需在 6.1.5 的换算里折算进设计空间
    }
  }
}

// src/core/ui-scale.ts —— 与引擎无关，可直接单测
export interface Insets {
  readonly top: number;
  readonly bottom: number;
  readonly left: number;
  readonly right: number;
}

export interface Rect {
  x: number;
  y: number;
  width: number;
  height: number;
}

/**
 * 把物理像素的四边内边距除以缩放系数，回到设计空间。
 * scale 为 0 或负数时按 1 处理，避免除零把整个布局算成 Infinity。
 */
export function insetsToDesign(insets: Insets, scale: number): Insets {
  const s = scale > 0 ? scale : 1;
  return {
    top: insets.top / s,
    bottom: insets.bottom / s,
    left: insets.left / s,
    right: insets.right / s,
  };
}

/** 在设计空间里扣掉四边安全区，得到可用矩形 */
export function safeRect(design: Rect, insets: Insets, scale: number): Rect {
  const d = insetsToDesign(insets, scale);
  return {
    x: design.x + d.left,
    y: design.y + d.top,
    width: design.width - d.left - d.right,
    height: design.height - d.top - d.bottom,
  };
}

// tests/ui-scale.test.ts
import { describe, it, expect } from 'vitest';
import { insetsToDesign, safeRect } from '../src/core/ui-scale';

describe('ui-scale', () => {
  it('物理像素除以缩放回到设计空间', () => {
    const d = insetsToDesign({ top: 88, bottom: 68, left: 0, right: 0 }, 2);
    expect(d.top).toBe(44);
    expect(d.bottom).toBe(34);
  });

  it('scale 为 0 时不产生 Infinity', () => {
    const d = insetsToDesign({ top: 10, bottom: 10, left: 10, right: 10 }, 0);
    expect(d.top).toBe(10);
  });

  it('安全区从设计矩形四边扣掉', () => {
    const r = safeRect(
      { x: 0, y: 0, width: 960, height: 540 },
      { top: 40, bottom: 20, left: 0, right: 0 },
      1,
    );
    expect(r.y).toBe(40);
    expect(r.height).toBe(480);
  });
});