《移动游戏产品的架构·客户端与移动运行时》7.2 多分辨率、刘海屏与安全区

// file: src/ui/layout-model.ts
// tier: L1
// verify: node --test test/ui/layout-model.test.ts

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

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

export interface Viewport {
  readonly width: number;
  readonly height: number;
  readonly insets: Insets;
}

export interface Design {
  readonly width: number;
  readonly height: number;
}

export interface Shape {
  readonly name: string;
  readonly viewport: Viewport;
}

export interface Fit {
  readonly scale: number;
  readonly content: Rect;
  readonly visible: Rect;
  readonly cropX: number;
  readonly cropY: number;
}

export type Anchor =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

export interface HudLayout {
  readonly name: string;
  readonly fit: Fit;
  readonly background: Rect;
  readonly safe: Rect;
  readonly topBar: Rect;
  readonly bottomBar: Rect;
  readonly pauseButton: Rect;
  readonly primaryButton: Rect;
  readonly touchSizePt: number;
}

export const ZERO_INSETS: Insets = { top: 0, right: 0, bottom: 0, left: 0 };
export const DESIGN_750: Design = { width: 750, height: 1334 };
export const TOP_BAR_HEIGHT = 112;
export const BOTTOM_BAR_HEIGHT = 144;
export const TOUCH_TARGET = 96;
export const MIN_TOUCH_PT = 44;

export const SHAPES: readonly Shape[] = [
  {
    name: "legacy-16x9",
    viewport: { width: 360, height: 640, insets: ZERO_INSETS },
  },
  {
    name: "notch-19.5x9",
    viewport: { width: 390, height: 844, insets: { top: 47, right: 0, bottom: 34, left: 0 } },
  },
  {
    name: "punch-hole-20x9",
    viewport: { width: 360, height: 800, insets: { top: 24, right: 0, bottom: 24, left: 0 } },
  },
  {
    name: "tablet-4x3",
    viewport: { width: 768, height: 1024, insets: { top: 0, right: 0, bottom: 20, left: 0 } },
  },
];

export function fitCover(view: Viewport, design: Design = DESIGN_750): Fit {
  const scale = Math.max(view.width / design.width, view.height / design.height);
  const content: Rect = {
    x: (view.width - design.width * scale) / 2,
    y: (view.height - design.height * scale) / 2,
    width: design.width * scale,
    height: design.height * scale,
  };
  return {
    scale,
    content,
    visible: {
      x: -content.x / scale,
      y: -content.y / scale,
      width: view.width / scale,
      height: view.height / scale,
    },
    cropX: content.width - view.width,
    cropY: content.height - view.height,
  };
}

export function safeRect(view: Viewport, fit: Fit): Rect {
  const left = view.insets.left / fit.scale;
  const top = view.insets.top / fit.scale;
  const right = view.insets.right / fit.scale;
  const bottom = view.insets.bottom / fit.scale;
  return {
    x: fit.visible.x + left,
    y: fit.visible.y + top,
    width: Math.max(0, fit.visible.width - left - right),
    height: Math.max(0, fit.visible.height - top - bottom),
  };
}

export function anchorRect(
  parent: Rect,
  width: number,
  height: number,
  anchor: Anchor,
  offsetX = 0,
  offsetY = 0,
): Rect {
  let x = parent.x;
  let y = parent.y;
  if (anchor.endsWith("center")) {
    x = parent.x + (parent.width - width) / 2;
  } else if (anchor.endsWith("right")) {
    x = parent.x + parent.width - width;
  }
  if (anchor.startsWith("center")) {
    y = parent.y + (parent.height - height) / 2;
  } else if (anchor.startsWith("bottom")) {
    y = parent.y + parent.height - height;
  }
  return { x: x + offsetX, y: y + offsetY, width, height };
}

export function layoutHud(shape: Shape, design: Design = DESIGN_750): HudLayout {
  const fit = fitCover(shape.viewport, design);
  const safe = safeRect(shape.viewport, fit);
  const topHeight = Math.min(TOP_BAR_HEIGHT, safe.height / 3);
  const bottomHeight = Math.min(BOTTOM_BAR_HEIGHT, safe.height / 3);
  const topBar: Rect = { x: safe.x, y: safe.y, width: safe.width, height: topHeight };
  const bottomBar: Rect = {
    x: safe.x,
    y: safe.y + safe.height - bottomHeight,
    width: safe.width,
    height: bottomHeight,
  };
  return {
    name: shape.name,
    fit,
    background: { x: 0, y: 0, width: shape.viewport.width, height: shape.viewport.height },
    safe,
    topBar,
    bottomBar,
    pauseButton: anchorRect(topBar, TOUCH_TARGET, TOUCH_TARGET, "top-right", -8, 0),
    primaryButton: anchorRect(bottomBar, TOUCH_TARGET, TOUCH_TARGET, "bottom-center", 0, -12),
    touchSizePt: TOUCH_TARGET * fit.scale,
  };
}

export function contains(rect: Rect, x: number, y: number): boolean {
  return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
}