《Cocos 游戏开发入门》11.1 布局系统：锚点、对齐与适配

// src/ui/layout.ts —— mini2d UI 布局核心
export interface Size {
  width: number;
  height: number;
}

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

/** 锚点：父容器内的归一化坐标，两个分量都在 [0, 1] */
export interface Anchor {
  x: number;
  y: number;
}

/**
 * 把尺寸为 size 的子矩形按 anchor 摆进父矩形 parent。
 * 返回子矩形左上角坐标（mini2d 采用 y 向下的屏幕坐标系）。
 */
export function placeWithAnchor(
  parent: Rect,
  size: Size,
  anchor: Anchor,
): { x: number; y: number } {
  // 第一步：锚点落在父容器中的绝对位置
  const targetX = parent.x + anchor.x * parent.width;
  const targetY = parent.y + anchor.y * parent.height;
  // 第二步：子矩形自身的锚点按同一比例落在自身内，反推左上角
  return {
    x: targetX - anchor.x * size.width,
    y: targetY - anchor.y * size.height,
  };
}

export type Align9 =
  | 'top-left' | 'top' | 'top-right'
  | 'left' | 'center' | 'right'
  | 'bottom-left' | 'bottom' | 'bottom-right';

const ANCHOR_TABLE: Record<Align9, Anchor> = {
  'top-left': { x: 0, y: 0 },
  top: { x: 0.5, y: 0 },
  'top-right': { x: 1, y: 0 },
  left: { x: 0, y: 0.5 },
  center: { x: 0.5, y: 0.5 },
  right: { x: 1, y: 0.5 },
  'bottom-left': { x: 0, y: 1 },
  bottom: { x: 0.5, y: 1 },
  'bottom-right': { x: 1, y: 1 },
};

/**
 * 在父容器内按九宫格对齐，margin 是四周留白。
 * 留白通过先收缩父矩形实现，因此子控件永远不会压到父容器边缘。
 */
export function layoutInParent(
  parent: Rect,
  size: Size,
  align: Align9,
  margin = 0,
): { x: number; y: number } {
  const inner: Rect = {
    x: parent.x + margin,
    y: parent.y + margin,
    width: parent.width - margin * 2,
    height: parent.height - margin * 2,
  };
  return placeWithAnchor(inner, size, ANCHOR_TABLE[align]);
}

export type Direction = 'row' | 'column';

export interface ArrangeOptions {
  direction: Direction;
  spacing: number; // 相邻两项的间距
  offset: number; // 主轴起点偏移；居中时传 (容器长 - 内容长) / 2
}

export function arrange(
  sizes: readonly Size[],
  opts: ArrangeOptions,
): { x: number; y: number }[] {
  const out: { x: number; y: number }[] = [];
  let cursor = opts.offset;
  for (const s of sizes) {
    if (opts.direction === 'row') {
      out.push({ x: cursor, y: 0 });
      cursor += s.width + opts.spacing;
    } else {
      out.push({ x: 0, y: cursor });
      cursor += s.height + opts.spacing;
    }
  }
  return out;
}

export type ScaleMode =
  | 'exactFit'
  | 'noBorder'
  | 'showAll'
  | 'fixedHeight'
  | 'fixedWidth';

export function computeScale(
  design: Size,
  frame: Size,
  mode: ScaleMode,
): { scaleX: number; scaleY: number } {
  const sx = frame.width / design.width;
  const sy = frame.height / design.height;

  if (mode === 'exactFit') return { scaleX: sx, scaleY: sy };
  if (mode === 'noBorder') {
    const s = Math.max(sx, sy);
    return { scaleX: s, scaleY: s };
  }
  if (mode === 'showAll') {
    const s = Math.min(sx, sy);
    return { scaleX: s, scaleY: s };
  }
  if (mode === 'fixedHeight') return { scaleX: sy, scaleY: sy };
  return { scaleX: sx, scaleY: sx };
}

export interface Insets {
  top: number;
  bottom: number;
  left: number;
  right: number;
}

/**
 * 在帧矩形 frame 上扣掉四边安全区，得到可用矩形。
 * insets 通常是物理像素，先除以缩放系数回到设计空间。
 */
export function applySafeArea(
  frame: Rect,
  insets: Insets,
  scale: number,
): Rect {
  const top = insets.top / scale;
  const bottom = insets.bottom / scale;
  const left = insets.left / scale;
  const right = insets.right / scale;
  return {
    x: frame.x + left,
    y: frame.y + top,
    width: frame.width - left - right,
    height: frame.height - top - bottom,
  };
}

// tests/ui-layout.test.ts
import { describe, it, expect } from 'vitest';
import {
  placeWithAnchor,
  computeScale,
  applySafeArea,
} from '../src/ui/layout';

describe('layout', () => {
  it('锚点把控件钉在父容器右上角', () => {
    const p = placeWithAnchor(
      { x: 0, y: 0, width: 960, height: 640 },
      { width: 100, height: 40 },
      { x: 1, y: 0 },
    );
    expect(p).toEqual({ x: 860, y: 0 });
  });

  it('showAll 取较小缩放', () => {
    const s = computeScale(
      { width: 960, height: 640 },
      { width: 1170, height: 2532 },
      'showAll',
    );
    expect(s.scaleX).toBeCloseTo(1170 / 960);
    expect(s.scaleX).toBe(s.scaleY);
  });

  it('安全区在 y 向下坐标系里裁掉顶部刘海', () => {
    const safe = applySafeArea(
      { x: 0, y: 0, width: 960, height: 640 },
      { top: 88, bottom: 68, left: 0, right: 0 },
      1,
    );
    expect(safe.y).toBe(88);
    expect(safe.height).toBe(640 - 88 - 68);
  });
});

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

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

  start(): void {
    // 设计分辨率 960×640，按宽度等比缩放，高度方向超出部分可裁剪
    view.setDesignResolutionSize(960, 640, ResolutionPolicy.FIXED_WIDTH);
    const visible = view.getVisibleSize();

    const ui = this.node.getComponent(UITransform);
    ui?.setContentSize(visible.width, visible.height);
  }

  alignCoinLabel(): void {
    const label = this.coinLabel;
    if (label === null) return;
    const widget = label.addComponent(Widget);
    widget.isAlignTop = true;
    widget.isAlignRight = true;
    widget.top = 24;
    widget.right = 24;
    widget.alignMode = Widget.AlignMode.ON_WINDOW_RESIZE;
  }
}

// 挂在 HUD 根节点上；编辑器里还需在 Canvas 上勾选 Fit Height / Fit Width
this.node.addComponent(SafeArea);