WPF 五子棋項目文檔

1. 項目概述

本項目是一個使用 Windows Presentation Foundation (WPF) 技術棧和 C# 語言實現的桌面版五子棋（Gomoku）游戲。它遵循 MVVM（Model-View-ViewModel）設計模式，旨在提供一個結構清晰、可維護、可擴展的游戲應用。

主要功能：

標準的 15x15 棋盤。
支持黑白雙方輪流落子。
基本的落子邏輯（不能落在已有棋子的位置）。
簡單的勝負判斷邏輯（當前代碼中為簡化示例，需完整實現）。
顯示當前回合玩家。
提供“重新開始”功能。
視覺上呈現棋盤網格和棋子。

技術棧：

UI 框架: WPF (.NET)
語言: C#
設計模式: MVVM (Model-View-ViewModel)
開發環境: Visual Studio 2019/2022

2. 項目結構

項目采用了分層結構，將不同的職責分離到各自的目錄中：

      GomokuWPF/
├── Assets/                # 靜態資源目錄
│   ├── Images/           # (可選) 圖片資源，如棋子、背景圖等
│   └── Styles/           # XAML 樣式文件
│       └── BoardStyles.xaml # 棋盤和棋子的樣式定義
├── Models/               # 數據模型和核心業務邏輯
│   └── GameState.cs      # 游戲狀態、棋盤數據和核心游戲規則
├── ViewModels/           # 視圖模型，連接視圖和模型
│   └── MainViewModel.cs  # 主窗口對應的視圖模型
├── Views/                # 用戶界面 (XAML)
│   └── MainWindow.xaml   # 應用程序的主窗口
├── App.xaml              # WPF 應用程序入口定義
├── App.xaml.cs           # App.xaml 的 C# 代碼隱藏文件
└── GomokuWPF.csproj      # 項目文件 (由 VS 管理)

目錄說明:

Assets/: 存放不需要編譯的靜態資源，如樣式、圖片、字體等。
- Styles/: 專門存放 XAML ResourceDictionary 文件，用于定義 UI 控件的外觀和感覺。
Models/: 包含應用程序的核心數據結構和業務邏輯，獨立于 UI。GameState.cs 負責管理棋盤狀態、玩家回合、勝負判斷等。
ViewModels/: 包含視圖模型類。視圖模型是視圖（View）的數據上下文（DataContext），它從模型（Model）獲取數據，處理用戶交互（通過命令），并準備數據以便在視圖中顯示。
Views/: 包含所有的用戶界面定義文件（.xaml）及其關聯的代碼隱藏文件（.xaml.cs）。MainWindow.xaml 是用戶直接交互的主界面。
App.xaml/.cs: 應用程序的啟動入口。App.xaml 中通常定義全局資源（如樣式）和指定啟動窗口 (StartupUri)。

3. 組件詳解

3.1. App.xaml / App.xaml.cs

App.xaml:
- 定義應用程序級別的資源。通過 <Application.Resources> 和 <ResourceDictionary.MergedDictionaries>，它引入了 Assets/Styles/BoardStyles.xaml 中定義的樣式，使其在整個應用程序中可用。
- StartupUri="Views/MainWindow.xaml" 指定了應用程序啟動時首先加載并顯示的窗口。
App.xaml.cs:
- 是 App.xaml 的代碼隱藏文件。通常包含應用程序生命周期事件的處理代碼（如 OnStartup, OnExit），但在這個簡單的項目中，可能保持默認或為空。

3.2. Models/GameState.cs

職責: 封裝五子棋游戲的核心狀態和規則，與 UI 無關。
Player 枚舉: 定義了棋盤上可能的狀態：None (空), Black (黑子), White (白子)。
Board 屬性: Player[15, 15] 二維數組，存儲棋盤上每個交叉點的狀態。使用 get; 表示外部只能讀取，內部邏輯通過方法修改。
CurrentPlayer 屬性: Player 類型，指示當前輪到哪一方落子。private set; 確保只有 GameState 內部邏輯能改變玩家。
GameOver 屬性: bool 類型，標記游戲是否已經結束。private set; 同上。
MakeMove(int row, int col) 方法:
- 核心落子邏輯。
- 檢查游戲是否結束或目標位置是否已有棋子，如果是則直接返回。
- 在 Board 上記錄當前玩家的落子。
- 調用 CheckWin() 判斷當前落子是否導致勝利。
- 如果游戲勝利，設置 GameOver = true。
- 如果游戲未結束，切換 CurrentPlayer 到另一方。
CheckWin(int row, int col) 方法:
- （注意：當前代碼中返回 false，是簡化示例，需要完整實現！）
- 應包含完整的五子連珠判斷邏輯：檢查剛落子的位置 (row, col) 的水平、垂直、兩條對角線方向上，是否有連續五個同色棋子。
Reset() 方法: (注意：代碼中未顯式提供，但在 ViewModel 中被調用，應添加此方法)
- 用于重置游戲狀態。
- 將 Board 所有位置設為 Player.None。
- 將 CurrentPlayer 設回 Player.Black。
- 將 GameOver 設為 false。

3.3. ViewModels/MainViewModel.cs

職責: 作為 MainWindow.xaml 的 DataContext，連接 GameState (Model) 和 MainWindow (View)。處理用戶交互，并向 View 提供格式化后的數據和命令。
ObservableObject 基類: 實現了 INotifyPropertyChanged 接口，允許 ViewModel 在其屬性值改變時通知 View 更新綁定。OnPropertyChanged() 方法用于觸發此通知。
_game 字段: GameState 的私有實例，持有游戲狀態模型。
CurrentPlayerText 屬性: string 類型，根據 _game.CurrentPlayer 的值返回用戶友好的文本（"黑方回合" 或 "白方回合"）。當 _game.CurrentPlayer 改變時，需要調用 OnPropertyChanged(nameof(CurrentPlayerText)) 來更新 UI。
CurrentPlayerBrush 屬性: Brush 類型，根據 _game.CurrentPlayer 返回黑色或白色畫刷，用于 UI 提示。同樣需要 OnPropertyChanged 通知。
PlaceStoneCommand 屬性: ICommand 類型 (使用 RelayCommand<Point>)。綁定到棋盤單元格的點擊事件。
- ExecutePlaceStone(Point position): 命令的執行邏輯。接收點擊的坐標 position (相對于 ItemsControl 內的單元格)，計算對應的棋盤行列 row, col。調用 _game.MakeMove(row, col) 更新模型。然后調用 OnPropertyChanged 更新 CurrentPlayerText 和 CurrentPlayerBrush 以反映狀態變化。 （注意：這里需要 View 傳遞正確的坐標或單元格索引）。
RestartCommand 屬性: ICommand 類型 (使用 RelayCommand)。綁定到“重新開始”按鈕。
- ExecuteRestart(): 調用 _game.Reset() (假設已添加) 重置游戲模型。然后調用 OnPropertyChanged 更新相關 UI 屬性。
RelayCommand / RelayCommand<T>: 輔助類，提供了 ICommand 接口的簡單通用實現，簡化了在 ViewModel 中定義命令的過程。

3.4. Views/MainWindow.xaml

職責: 定義應用程序主窗口的結構、布局和外觀。通過數據綁定與 MainViewModel 交互。
<Window.DataContext>:
```
      <Window.DataContext><local:MainViewModel/>
</Window.DataContext>
```
?

在這里創建并設置了 MainViewModel 的實例作為窗口的數據上下文。窗口內的所有綁定默認都將相對于這個 MainViewModel 實例。
棋盤區域 (ItemsControl):
- ItemsSource="{Binding Board}": （注意：此綁定需要調整） GameState.Board 是一個二維數組，ItemsControl 通常期望綁定到一個一維集合（如 List<CellViewModel>）。MainViewModel 需要暴露一個適合綁定的集合，其中每個元素代表一個棋盤格，并包含其狀態（Player）和位置信息。
- <ItemsControl.ItemsPanel> 使用 UniformGrid 來將子項排列成 15x15 的網格。
- <ItemsControl.ItemTemplate>: 定義每個棋盤格（ItemsControl 的子項）的視覺表示。
  - Border: 代表一個棋盤格單元。
    - Width="40" Height="40": 定義單元格大小。
    - Background="{StaticResource BoardCellBrush}": 應用 BoardStyles.xaml 中定義的棋盤格背景（帶網格線）。
    - Command="{Binding DataContext.PlaceStoneCommand, RelativeSource={RelativeSource AncestorType=Window}}": 將單元格的交互（如點擊）綁定到 MainViewModel 的 PlaceStoneCommand。RelativeSource 用于查找父級 Window 的 DataContext。
    - CommandParameter="{Binding Position}": （注意：此綁定需要調整） 需要傳遞當前單元格的位置（行、列或索引）給命令。如果 ItemsSource 是 CellViewModel 列表，這里可以綁定到 CellViewModel 的 Position 屬性。
  - Ellipse: 代表棋子。
    - Width="30" Height="30": 定義棋子大小。
    - Fill="{Binding StoneBrush}": （注意：此綁定需要調整） 綁定到 CellViewModel 的一個屬性（如 StoneBrush），該屬性根據 CellViewModel 的狀態（黑/白/空）返回相應的畫刷（黑色、白色或透明）。
控制面板 (StackPanel):
- Button Content="重新開始":
  - Command="{Binding RestartCommand}": 綁定到 MainViewModel 的 RestartCommand。
- TextBlock:
  - Text="{Binding CurrentPlayerText}": 顯示當前回合玩家文本。
  - Foreground="{Binding CurrentPlayerBrush}": 根據當前玩家設置文本顏色。

3.5. Assets/Styles/BoardStyles.xaml

職責: 集中定義棋盤、棋格和棋子的視覺樣式，方便復用和修改。
BoardCellBrush (DrawingBrush): 定義棋盤格的背景。
- 使用 DrawingGroup 組合了一個米色背景 (RectangleGeometry) 和兩條居中的灰色線條 (GeometryDrawing) 來模擬棋盤網格。
- TileMode="Tile" 和 Viewport 設置使這個 40x40 的圖案在 ItemsControl 的單元格背景中平鋪，形成連續的網格。
GridPen (Pen): 定義網格線的畫筆（顏色、粗細）。
BlackStoneBrush / WhiteStoneBrush (RadialGradientBrush): 定義黑棋和白棋的填充畫刷。使用徑向漸變模擬棋子的光澤和立體感。

4. 核心概念

MVVM (Model-View-ViewModel):
- Model (GameState.cs): 代表數據和業務邏輯。不知道 View 和 ViewModel。
- View (MainWindow.xaml): 代表 UI。通過數據綁定與 ViewModel 交互。直接引用 ViewModel (通常通過 DataContext)，但不直接引用 Model。
- ViewModel (MainViewModel.cs): 連接 Model 和 View 的橋梁。持有 Model 實例，向 View 暴露數據（通過屬性）和操作（通過命令）。處理 View 的交互請求，更新 Model，并通過 INotifyPropertyChanged 通知 View 更新。
數據綁定 ({Binding ...} syntax): WPF 的核心機制，用于在 UI 元素（View）的屬性和數據源（通常是 ViewModel）的屬性之間建立連接。當數據源屬性變化時，UI 會自動更新，反之亦然（對于雙向綁定）。
命令 (ICommand): WPF 中處理用戶交互（如按鈕點擊）的標準方式。ViewModel 實現 ICommand 接口（通常通過 RelayCommand），View 將控件的 Command 屬性綁定到 ViewModel 的命令屬性。這使得交互邏輯可以放在 ViewModel 中，保持 View 的簡潔。
資源字典 (ResourceDictionary): 用于存儲可重用的資源，如樣式（Style）、畫刷（Brush）、模板（ControlTemplate, DataTemplate）等。可以合并到 App.xaml 或控件的 Resources 中使用。StaticResource 用于在 XAML 中引用這些資源。
INotifyPropertyChanged: 接口，當對象的屬性值更改時，向綁定客戶端發出通知。ViewModel 必須實現此接口，以便在數據變化時驅動 UI 更新。ObservableObject 是一個常見的基類實現。

5. 游戲流程

啟動: 應用程序啟動，App.xaml 指定 MainWindow.xaml 作為啟動窗口。
初始化: MainWindow.xaml 加載，其實例的 DataContext 被設置為一個新的 MainViewModel 實例。MainViewModel 在其構造函數中創建 GameState 實例和命令。
UI 渲染:
- ItemsControl 嘗試綁定到 MainViewModel 的 Board 屬性（需要調整實現）來獲取棋盤數據。
- ItemsControl 使用 UniformGrid 創建 15x15 的布局。
- 對于每個棋盤格，ItemTemplate 被實例化。Border 的背景應用 BoardCellBrush，Ellipse 的填充根據棋盤格狀態（通過綁定）設置。
- 控制面板的 TextBlock 綁定到 CurrentPlayerText 和 CurrentPlayerBrush，顯示初始狀態（"黑方回合"，黑色）。
- "重新開始" 按鈕綁定到 RestartCommand。
玩家落子:
- 玩家點擊棋盤上的一個空單元格 (Border)。
- 該 Border 的 Command (綁定到 PlaceStoneCommand) 被觸發。
- MainViewModel.ExecutePlaceStone 方法被調用，傳入點擊位置（需要正確傳遞）。
- ExecutePlaceStone 計算行列，調用 _game.MakeMove(row, col)。
- GameState.MakeMove 更新 Board 數組，檢查勝利條件，然后切換 CurrentPlayer。
- ExecutePlaceStone 調用 OnPropertyChanged 通知 UI 更新 CurrentPlayerText 和 CurrentPlayerBrush。
- （關鍵缺失/需調整）: Board 數組的變化需要一種機制來更新 ItemsControl 中對應單元格的 Ellipse 的 Fill 屬性。這通常通過讓 ItemsSource 綁定到一個 ObservableCollection<CellViewModel>，并在 MakeMove 后更新相應的 CellViewModel 的狀態屬性來實現。
判斷勝負:
- GameState.CheckWin 方法（需要完整實現）在每次落子后被調用。
- 如果檢測到勝利，GameState.GameOver 設置為 true。ViewModel 可以暴露這個狀態給 View，例如禁用棋盤交互或顯示勝利消息。
重新開始:
- 玩家點擊 "重新開始" 按鈕。
- 按鈕的 Command (綁定到 RestartCommand) 被觸發。
- MainViewModel.ExecuteRestart 方法被調用。
- ExecuteRestart 調用 _game.Reset() (假設已添加)。
- GameState.Reset 清空棋盤，重置玩家和游戲狀態。
- ExecuteRestart 調用 OnPropertyChanged 更新 UI 顯示（回合提示、棋盤視覺）。（同樣需要機制更新棋盤所有單元格的視覺）

6. 如何編譯和運行

環境: 確保已安裝 Visual Studio 2019 或 2022，并包含 .NET 桌面開發工作負載。
打開項目: 使用 Visual Studio 打開 GomokuWPF.sln 文件（如果存在）或 GomokuWPF.csproj 文件。
構建項目: 在 Visual Studio 菜單中選擇 "生成" -> "生成解決方案" (或按 F6)。檢查 "輸出" 窗口是否有編譯錯誤。
- 注意: 根據文檔分析，原始代碼片段在 Board 綁定和 Reset 方法方面可能存在不一致或缺失，可能需要進行少量修改才能成功編譯和按預期運行。具體來說：
  - 在 GameState.cs 中添加 Reset() 方法。
  - 修改 MainViewModel.cs，使其暴露一個適合 ItemsControl 綁定的棋盤數據集合（例如 ObservableCollection<CellViewModel>），并在 MakeMove 和 Reset 后更新這個集合。
  - 修改 MainWindow.xaml 中的 ItemsControl 綁定 (ItemsSource, CommandParameter, Fill) 以匹配新的 ViewModel 結構。
運行項目: 按 F5 鍵或點擊 Visual Studio 工具欄上的 "啟動" 按鈕。應用程序主窗口 (MainWindow) 應該會顯示出來。

7. 潛在的擴展和改進

實現完整的勝負判斷: 填充 GameState.CheckWin 方法的邏輯。
完善 ViewModel 對 Board 的暴露: 如上所述，使用 ObservableCollection<CellViewModel> 替代直接暴露二維數組，以實現正確的 UI 更新。CellViewModel 可以包含 Row, Col, Player 狀態，以及用于綁定的 StoneBrush 屬性。
游戲結束提示: 當 GameOver 為 true 時，在 UI 上明確顯示勝利者，并可能禁用棋盤交互。
悔棋功能: 添加撤銷上一步操作的邏輯。
平局判斷: 實現棋盤滿但無勝負的情況。
AI 對手: 添加一個 AI 邏輯模塊，可以選擇與電腦對戰。
音效: 在落子、勝利時播放聲音。
設置選項: 允許配置棋盤大小、先手方等。
網絡對戰: 實現通過網絡與其他玩家對戰的功能。
優化樣式: 改進棋盤和棋子的視覺效果。