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 逻辑模块，可以选择与电脑对战。
音效: 在落子、胜利时播放声音。
设置选项: 允许配置棋盘大小、先手方等。
网络对战: 实现通过网络与其他玩家对战的功能。
优化样式: 改进棋盘和棋子的视觉效果。