# UI组件设计详设文档

> **文档版本**: v1.0  
> **撰写人**: UI/UX设计师 & 前端架构师  
> **创建日期**: 2024年9月11日  

## 1. 设计系统与主题

### 1.1 设计语言

- **主题**: 暗黑科技风 (Dark/Tech Theme)，与原型设计稿保持一致。
- **主色调**:
    - 背景: `#1A202C` (深灰蓝)
    - 主色: `#00BFFF` (深天蓝，用于按钮、高亮、链接)
    - 辅助色: `#4A5568` (中灰，用于边框、分割线)
    - 强调色: `#FF4500` (橙红，用于警告、错误提示、攻击命中)
- **字体**:
    - `sans-serif` 系统默认无衬线字体。
    - 使用 `rem` 和 `em` 作为字体单位，以支持可访问性。

### 1.2 Design Token

所有颜色、字体大小、间距、圆角等样式参数都将通过Design Token进行管理，以`Sass`变量形式实现。

```scss
// src/styles/tokens.scss

// Colors
$color-background: #1A202C;
$color-primary: #00BFFF;
$color-secondary: #4A5568;
$color-accent: #FF4500;
$color-text-primary: #FFFFFF;
$color-text-secondary: #A0AEC0;

// Spacing
$spacing-xs: 0.25rem; // 4px
$spacing-sm: 0.5rem;  // 8px
$spacing-md: 1rem;    // 16px
$spacing-lg: 1.5rem;  // 24px
$spacing-xl: 2rem;    // 32px

// Border Radius
$border-radius-sm: 4px;
$border-radius-md: 8px;
$border-radius-lg: 16px;
```

## 2. 原子组件 (Atoms)

原子组件是UI构成的最小单元，不可再分。

### 2.1 `Button` 组件

- **功能**: 标准按钮，支持不同变体和状态。
- **Props**:
  ```typescript
  interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
    variant?: 'primary' | 'secondary' | 'danger'; // 样式变体
    size?: 'sm' | 'md' | 'lg'; // 尺寸
    isLoading?: boolean; // 加载状态
    leftIcon?: React.ReactNode;
    rightIcon?: React.ReactNode;
  }
  ```
- **样式**:
    - `primary`: 主色背景，白色文字。
    - `secondary`: 辅助色边框，主色文字。
    - `danger`: 强调色背景，白色文字。
    - `disabled`: 降低透明度，禁用鼠标事件。
    - `isLoading`: 显示加载动画，禁用按钮。

### 2.2 `Input` 组件

- **功能**: 文本输入框。
- **Props**:
  ```typescript
  interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
    label?: string; // 标签
    errorMessage?: string; // 错误信息
    leftIcon?: React.ReactNode;
  }
  ```
- **样式**:
    - `focus`: 主色边框高亮。
    - `error`: 强调色边框和错误信息。

### 2.3 `Spinner` 组件

- **功能**: 加载指示器。
- **Props**:
  ```typescript
  interface SpinnerProps {
    size?: 'sm' | 'md' | 'lg'; // 尺寸
    color?: string; // 颜色
  }
  ```

### 2.4 `Icon` 组件

- **功能**: 图标库封装，使用`react-icons`。
- **Props**:
  ```typescript
  import { IconType } from 'react-icons';
  
  interface IconProps {
    as: IconType; // 图标组件
    size?: string | number;
    color?: string;
  }
  ```

## 3. 分子组件 (Molecules)

由原子组件组合而成，完成特定功能。

### 3.1 `FormField` 组件

- **构成**: `Input` + `Label` + `ErrorMessage`
- **功能**: 完整的表单字段，包含标签和验证逻辑。

### 3.2 `PlayerAvatar` 组件

- **构成**: `Avatar` + `Text`
- **功能**: 显示玩家头像和昵称。
- **Props**:
  ```typescript
  interface PlayerAvatarProps {
    player: {
      avatarUrl: string;
      nickname: string;
      isOwner?: boolean; // 是否是房主
      isReady?: boolean; // 是否已准备
    };
    size?: 'md' | 'lg';
  }
  ```
- **样式**:
    - `isReady`: 头像外圈显示主色高亮。
    - `isOwner`: 昵称旁显示皇冠图标。

### 3.3 `RoomListItem` 组件

- **构成**: `Text` + `Icon` + `Button`
- **功能**: 在房间列表中显示单个房间的信息。
- **Props**:
  ```typescript
  interface RoomListItemProps {
    room: {
      roomCode: string;
      name: string;
      playerCount: number;
      isLocked: boolean;
    };
    onJoin: (roomCode: string) => void;
  }
  ```

## 4. 生物组件 (Organisms)

由分子和原子组件构成的更复杂的UI部分。

### 4.1 `GameBoard` 组件

- **功能**: 核心游戏棋盘UI，负责渲染10x10的网格和飞机。
- **构成**: 多个 `GridCell` 组件。
- **Props**:
  ```typescript
  interface GameBoardProps {
    boardState: BoardState; // 棋盘状态数据
    isMyBoard: boolean; // 是否是自己的棋盘
    onCellClick: (position: { x: number, y: number }) => void; // 单元格点击事件
    placedPlanes?: Plane[]; // 预放置的飞机
  }
  ```
- **`GridCell` 子组件**:
    - 根据单元格状态(`empty`, `plane_part`, `miss`, `hit`, `destroy`)显示不同样式。
    - 在对手棋盘上，`plane_part`状态默认不显示，除非被攻击过。
    - 鼠标悬停在可攻击的单元格上时显示准星光标。

### 4.2 `PlanePlacementPanel` 组件

- **功能**: 飞机布置阶段的操作面板，允许玩家拖拽或旋转飞机。
- **构成**: `PlanePreview` 组件 + `Button` (旋转/确认)
- **Props**:
  ```typescript
  interface PlanePlacementPanelProps {
    onPlanesConfirm: (planes: Plane[]) => void;
  }
  ```
- **交互**:
    - 提供3个默认形状的飞机供拖拽到棋盘。
    - 支持点击飞机进行90度旋转。
    - 棋盘上会实时预览飞机位置，并对非法位置（越界、重叠）进行红色高亮提示。

### 4.3 `Header` 组件

- **功能**: 应用的全局顶部导航栏。
- **构成**: `Logo` + `UserInfo` + `SettingsButton`

## 5. 模板组件 (Templates)

定义页面的整体布局结构。

### 5.1 `MainLayout` 组件

- **功能**: 应用的主布局，包含页头、内容区、页脚。
- **构成**: `Header` + `children` + `Footer`
- **插槽(Slots)**: 通过`children` prop 插入页面具体内容。

## 6. 页面组件 (Pages)

完整的页面，由模板和多个生物/分子组件构成。

### 6.1 `HomePage`

- **路径**: `/`
- **功能**: 游戏入口页面，包含"创建房间"和"加入房间"按钮。
- **组件构成**: `MainLayout`, `Logo`, `Button`。

### 6.2 `RoomListPage`

- **路径**: `/rooms`
- **功能**: 显示公开的房间列表，支持刷新和搜索。
- **组件构成**: `MainLayout`, `RoomListItem`, `Spinner`, `Button`。

### 6.3 `RoomWaitingPage`

- **路径**: `/room/:roomCode`
- **功能**: 玩家等待页面，显示双方玩家信息和准备状态。
- **组件构成**: `MainLayout`, `PlayerAvatar` (x2), `Button` (准备/开始游戏), `ChatBox` (可选)。
- **逻辑**:
    - 房主显示"开始游戏"按钮，当所有玩家准备好后激活。
    - 其他玩家显示"准备"按钮。
    - 实时监听WebSocket的`ROOM_STATE_UPDATE`事件更新UI。

### 6.4 `GamePage`

- **路径**: `/game/:gameId`
- **功能**: 核心游戏对战页面。
- **组件构成**:
    - `MainLayout`
    - `GameBoard` (我方棋盘)
    - `GameBoard` (敌方棋盘)
    - `GameStatusPanel`: 显示当前回合、倒计时、游戏日志。
    - `PlanePlacementPanel`: 仅在飞机布置阶段显示。
- **逻辑**:
    - 页面加载时从Zustand Store获取游戏状态。
    - 监听WebSocket的`GAME_STATE_UPDATE`事件更新整个页面。
    - 根据游戏阶段(`placing`, `battling`, `finished`)渲染不同UI。
    - 在`finished`阶段，显示游戏结果弹窗(`GameResultModal`)。