戰鬥 UI 模式 A - 分割畫面實作
此技能引導實作分割畫面戰鬥 UI,將垂直的劇場模式轉換為橫向對戰佈局。
架構概覽
┌───────────────────────────────────────────────────┐
│ 回合指示器 │ 階段管線 │ 修飾符 │ ← PhaseHeader
├──────────────────┴───────┬───────────┴────────────┤
│ │ │
│ 玩家面板 │ 敵方面板 │ ← ConfrontationZone
│ (CharacterPanel) │ (CharacterPanel) │
│ │ │
├──────────────────────────┴────────────────────────┤
│ 快速行動 (側邊/切換) │ 主要行動 │ ← ActionDock
└───────────────────────────────┴───────────────────┘
元件層級結構
Combat.tsx (場景協調器)
├── CombatLayout.tsx (CSS 網格容器)
│ ├── PhaseHeader.tsx (頂部狀態列)
│ │ ├── TurnIndicator
│ │ ├── PhasePipeline
│ │ ├── SideActionCounter
│ │ └── ApproachModifier
│ │
│ ├── ConfrontationZone.tsx (戰鬥區域)
│ │ ├── CharacterPanel.tsx (玩家變體)
│ │ │ ├── CharacterSprite
│ │ │ ├── IdentityBar
│ │ │ ├── ResourceBars (HP/CP)
│ │ │ └── BuffBar
│ │ │
│ │ ├── VSDivider.tsx (中央標誌)
│ │ │
│ │ └── CharacterPanel.tsx (敵方變體)
│ │ ├── CharacterSprite
│ │ ├── IdentityBar (名稱、階級、元素)
│ │ ├── HealthBar
│ │ ├── DefenseStats
│ │ └── BuffBar
│ │
│ └── ActionDock.tsx (技能列)
│ ├── QuickActionsSection
│ │ ├── QuickActionCard (側邊技能)
│ │ └── QuickActionCard (切換技能)
│ ├── MainActionsSection
│ │ └── MainActionCard (主要技能)
│ └── ControlButtons (自動、結束回合)
│
└── FloatingTextLayer (z-50, 不變)
檔案結構
src/components/combat/
├── index.ts # Barrel 匯出
├── CombatLayout.tsx # 網格容器
├── PhaseHeader.tsx # 頂部狀態列
├── ConfrontationZone.tsx # 玩家 vs 敵方區域
├── CharacterPanel.tsx # 可重複使用的角色顯示
├── VSDivider.tsx # 中央 VS 標誌
├── ActionDock.tsx # 底部技能列
├── QuickActionCard.tsx # 精簡側邊/切換卡片
└── MainActionCard.tsx # 大型主要技能卡片
實作工作流程
步驟 1:識別目標元件
詢問使用者要實作哪個元件:
- CombatLayout - 新實作從此開始
- PhaseHeader - 頂部狀態列
- ConfrontationZone - 包含兩個面板的戰鬥區域
- CharacterPanel - 單個角色顯示
- VSDivider - 中央標誌和效果
- ActionDock - 底部技能列
- QuickActionCard - 精簡技能卡片變體
- MainActionCard - 大型技能卡片變體
步驟 2:載入元件參考
根據選擇,載入適當的參考:
- 佈局/結構:參閱 layout-specs.md
- 元件屬性:參閱 component-interfaces.md
- 樣式指南:參閱 styling-tokens.md
- 動畫規格:參閱 animations.md
步驟 3:產生元件程式碼
遵循元件模板模式:
import React from 'react';
import { cn } from '@/lib/utils'; // 如果使用 cn 工具函式
interface ComponentNameProps {
// 來自 component-interfaces.md 的屬性
}
export const ComponentName: React.FC<ComponentNameProps> = ({
// 解構屬性
}) => {
return (
<div className={cn(
// 來自 styling-tokens.md 的基礎樣式
// 條件樣式
)}>
{/* 元件內容 */}
</div>
);
};
步驟 4:連接到 Combat.tsx
建立元件後:
- 從
components/combat/index.ts匯出 - 在
Combat.tsx中匯入 - 取代對應區段
- 從現有狀態傳遞必要的屬性
快速實作指令
建立所有檔案(支架)
# 建立目錄
mkdir -p src/components/combat
# 建立所有元件檔案
touch src/components/combat/{index,CombatLayout,PhaseHeader,ConfrontationZone,CharacterPanel,VSDivider,ActionDock,QuickActionCard,MainActionCard}.tsx
Barrel 匯出模板
// src/components/combat/index.ts
export { CombatLayout } from './CombatLayout';
export { PhaseHeader } from './PhaseHeader';
export { ConfrontationZone } from './ConfrontationZone';
export { CharacterPanel } from './CharacterPanel';
export { VSDivider } from './VSDivider';
export { ActionDock } from './ActionDock';
export { QuickActionCard } from './QuickActionCard';
export { MainActionCard } from './MainActionCard';
從現有程式碼對應屬性
從 App.tsx → Combat.tsx(不變)
player: Player
enemy: Enemy
turnState: 'PLAYER' | 'ENEMY_TURN'
turnPhase: TurnPhaseState
combatState: CombatState
onUseSkill: (skill: Skill) => void
onPassTurn: () => void
onToggleAutoCombat: () => void
autoCombatEnabled: boolean
Combat.tsx → 新元件
// PhaseHeader
turnState, turnPhase, combatState.approach
// ConfrontationZone
player, enemy, playerStats, enemyStats
// CharacterPanel (玩家)
character: player, stats: playerStats, variant: 'player'
// CharacterPanel (敵方)
character: enemy, stats: enemyStats, variant: 'enemy'
// ActionDock
skills: player.skills, turnPhase, onUseSkill, onPassTurn
遷移策略
階段 1:佈局基礎
- 建立
CombatLayout.tsx,使用 CSS 網格 - 建立佔位元件
- 在 Combat.tsx 中新增功能旗標
階段 2:元件提取
- 實作
CharacterPanel(從 PlayerHUD + CinematicViewscreen 提取) - 實作
ActionDock(從技能網格提取) - 實作
PhaseHeader(從內聯指示器提取)
階段 3:視覺打磨
- 新增帶有效果的
VSDivider - 實作動畫
- 調整浮動文字位置
階段 4:清理
- 移除舊的劇場模式程式碼
- 移除功能旗標
- 更新測試
參考檔案
- layout-specs.md - CSS 網格結構、響應式斷點
- component-interfaces.md - 所有元件的 TypeScript 介面
- styling-tokens.md - 顏色、間距、排版權杖
- animations.md - 動畫關鍵影格和轉場
輸出格式
產生 TypeScript React 元件,包含:
- 屬性的 TypeScript 介面
- 樣式的 Tailwind CSS(符合現有程式碼庫)
- 響應式類別(行動裝置退回垂直佈局)
- 適當的 記憶化(卡片使用 React.memo)
- 無障礙屬性(aria-labels、roles)
現有程式碼參考
實作時,參考這些現有檔案:
| 新元件 | 參考來源 |
|---|---|
| CharacterPanel (玩家) | src/components/PlayerHUD.tsx |
| CharacterPanel (敵方) | src/scenes/Combat.tsx 第 113-305 行 |
| ActionDock | src/scenes/Combat.tsx 第 308-607 行 |
| QuickActionCard | src/components/SkillCard.tsx |
| MainActionCard | src/components/SkillCard.tsx |
| PhaseHeader | src/scenes/Combat.tsx 第 311-328 行 |