项目概述

本项目是一个基于 Electron 开发的中国象棋游戏应用，提供完整的象棋对弈体验，包括人机对战、计时功能、走棋记录和游戏存档等特性。该应用采用现代前端技术栈构建，界面简洁友好，代码结构清晰，适合作为学习 Electron 和游戏开发的示例。同时新增鸿蒙 PC 平台适配方案，通过 Electron 鸿蒙适配层实现原生运行支持，核心功能（如 AI 对战、计时系统、存档加载）在鸿蒙端完全兼容，且优化了渲染性能与系统适配性。

功能特性

• 完整的中国象棋规则实现：包括车、马、象、士、将、炮、兵七种棋子的标准移动规则
• 人机对战：内置 AI 对手，支持三种难度级别（简单、中等、困难）（鸿蒙端优化性能）
• 游戏计时系统：为红方和黑方提供独立计时器，增强游戏竞争性（适配鸿蒙时间 API）
• 走棋记录：实时记录和显示每一步走棋，支持历史记录查看
• 游戏控制功能：支持新游戏、重新开始、撤销走棋
• 游戏存档：支持保存和加载游戏进度（适配鸿蒙本地存储机制）
• 响应式界面：适配不同窗口大小及鸿蒙 PC 标准分辨率，提供良好的用户体验
• 游戏帮助：提供游戏规则说明和操作指南
• 跨平台支持：原生支持 Windows/macOS/Linux，改造后支持鸿蒙 PC 系统
• 鸿蒙特性适配：兼容鸿蒙窗口管理、系统权限、Canvas 渲染优化、硬件加速兼容

技术栈

• 核心框架：Electron ^34.0.0（鸿蒙适配最低要求版本）
• 前端技术：JavaScript、HTML5 Canvas（鸿蒙端优化渲染）、CSS3
• 本地存储：localStorage（鸿蒙端兼容适配）
• 鸿蒙工具链：DevEco Studio 5.0+、鸿蒙 SDK API 20+
• 构建工具：npm、ohos-build-cli

核心代码解析

1. Electron 主进程 (main.js) - 鸿蒙适配修改

Electron 主进程负责创建和管理应用窗口，处理应用生命周期事件，并设置与渲染进程的通信。以下是针对鸿蒙 PC 的核心适配修改：

javascript

运行

// 中国象棋 - Electron主进程（鸿蒙适配版）
const { app, BrowserWindow } = require('electron');
const path = require('path');
let mainWindow;

function createWindow() {
  // 鸿蒙PC必须禁用硬件加速（解决窗口不显示、Canvas渲染异常问题）
  app.disableHardwareAcceleration();

  mainWindow = new BrowserWindow({
    width: 900,
    height: 700,
    resizable: true,
    maximizable: true,
    autoHideMenuBar: false,
    icon: path.join(__dirname, 'src', 'assets', 'icon.png'),
    webPreferences: {
      preload: path.join(__dirname, 'src', 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
      enableRemoteModule: false,
      devTools: true
    },
    // 鸿蒙PC窗口适配优化
    fullscreenable: false, // 禁用全屏（避免鸿蒙系统兼容性冲突）
    titleBarStyle: 'default' // 适配鸿蒙原生标题栏样式
  });
  
  // 加载应用的index.html
  mainWindow.loadFile(path.join(__dirname, 'src', 'index.html'));
  
  // 开发环境下打开开发者工具
  if (process.argv.includes('--dev')) {
    mainWindow.webContents.openDevTools();
  }
  
  // 窗口事件监听（保持原有逻辑）
  mainWindow.on('closed', function () {
    mainWindow = null;
  });
  
  mainWindow.on('maximize', function () {
    mainWindow.webContents.send('window-maximized');
  });
  
  mainWindow.on('unmaximize', function () {
    mainWindow.webContents.send('window-unmaximized');
  });
}

// 应用生命周期事件处理（保持原有逻辑）
app.on('ready', createWindow);
app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit();
});
app.on('activate', function () {
  if (mainWindow === null) createWindow();
});

// 新增：鸿蒙环境检测与适配
if (process.env.OHOS_ENV) {
  console.log('Running on HarmonyOS PC, applying compatibility patches');
  // 鸿蒙端禁用不必要的API调用
  app.on('browser-window-focus', function () {});
  app.on('browser-window-blur', function () {});
}

2. 游戏状态管理 - 鸿蒙兼容优化

游戏状态管理逻辑无需大幅修改，仅针对鸿蒙端存储特性优化存档序列化：

javascript

运行

// 游戏状态（鸿蒙兼容优化）
let gameState = {
    board: [],
    currentPlayer: GAME_CONSTANTS.PLAYERS.RED,
    selectedPiece: null,
    gameStatus: GAME_CONSTANTS.GAME_STATUS.READY,
    moveCount: 0,
    moveHistory: [],
    redTime: 0,
    blackTime: 0,
    timerInterval: null,
    aiMode: true,
    aiDifficulty: 2,
    aiThinking: false,
    // 新增：鸿蒙端存储兼容标记
    isHarmonyOS: process.env.OHOS_ENV ? true : false
};

3. Canvas 渲染优化（鸿蒙端）

针对鸿蒙 PC 的 web 引擎特性，优化 Canvas 渲染性能，避免动画卡顿：

javascript

运行

// 渲染优化 - 鸿蒙端适配
function renderBoard() {
  const canvas = document.getElementById('chessBoardCanvas');
  const ctx = canvas.getContext('2d');
  
  // 鸿蒙端Canvas抗锯齿优化
  ctx.imageSmoothingEnabled = true;
  ctx.imageSmoothingQuality = 'high';
  
  // 原有渲染逻辑保持不变
  // ...（棋盘绘制、坐标计算等代码）
}

// 优化重绘机制：使用requestAnimationFrame替代setTimeout
function scheduleRender() {
  if (gameState.isHarmonyOS) {
    requestAnimationFrame(() => {
      renderBoard();
      renderPieces();
    });
  } else {
    // 其他平台保持原有逻辑
    setTimeout(() => {
      renderBoard();
      renderPieces();
    }, 16);
  }
}

4. AI 对战系统 - 鸿蒙性能优化

鸿蒙端优化 AI 计算逻辑，减少资源占用，避免界面卡顿：

javascript

运行

// AI走棋函数（鸿蒙性能优化版）
function makeAIMove() {
  if (!gameState.aiMode || gameState.gameStatus !== GAME_CONSTANTS.GAME_STATUS.PLAYING || 
      gameState.currentPlayer !== GAME_CONSTANTS.PLAYERS.BLACK) {
    return;
  }
  
  gameState.aiThinking = true;

  // 鸿蒙端优化：缩短AI思考延迟，减少UI阻塞
  const delay = gameState.isHarmonyOS ? 300 : 500;
  
  setTimeout(() => {
    const validMoves = [];
    
    // 遍历棋盘，找出所有可能的走法（原有逻辑保持不变）
    for (let row = 0; row < GAME_CONSTANTS.BOARD_ROWS; row++) {
      for (let col = 0; col < GAME_CONSTANTS.BOARD_COLS; col++) {
        const piece = gameState.board[row][col];
        if (piece && piece.player === GAME_CONSTANTS.PLAYERS.BLACK) {
          for (let toRow = 0; toRow < GAME_CONSTANTS.BOARD_ROWS; toRow++) {
            for (let toCol = 0; toCol < GAME_CONSTANTS.BOARD_COLS; toCol++) {
              if (isValidMove(row, col, toRow, toCol)) {
                const moveScore = evaluateMove(row, col, toRow, toCol);
                validMoves.push({ fromRow: row, fromCol: col, toRow: toRow, toCol: toCol, score: moveScore });
              }
            }
          }
        }
      }
    }
    
    // 鸿蒙端优化：简化AI决策逻辑（中等/简单难度），提升响应速度
    let bestMove;
    switch (gameState.aiDifficulty) {
      case 1: // 简单模式
        if (gameState.isHarmonyOS) {
          // 鸿蒙端：60%概率随机选择，提升运行速度
          bestMove = Math.random() < 0.4 ? 
            validMoves.reduce((best, move) => (move.score > best.score) ? move : best) :
            validMoves[Math.floor(Math.random() * validMoves.length)];
        } else {
          bestMove = Math.random() < 0.5 ? 
            validMoves.reduce((best, move) => (move.score > best.score) ? move : best) :
            validMoves[Math.floor(Math.random() * validMoves.length)];
        }
        break;
      case 2: // 中等模式
        if (gameState.isHarmonyOS) {
          // 鸿蒙端：80%概率选择最佳走法
          bestMove = Math.random() < 0.8 ? 
            validMoves.reduce((best, move) => (move.score > best.score) ? move : best) :
            validMoves[Math.floor(Math.random() * validMoves.length)];
        } else {
          bestMove = Math.random() < 0.75 ? 
            validMoves.reduce((best, move) => (move.score > best.score) ? move : best) :
            validMoves[Math.floor(Math.random() * validMoves.length)];
        }
        break;
      case 3: // 困难模式（保持原有逻辑）
        bestMove = validMoves.reduce((best, move) => (move.score > best.score) ? move : best);
        break;
    }
    
    // 执行选中的走法（原有逻辑保持不变）
    if (bestMove) {
      handlePieceClick(bestMove.fromRow, bestMove.fromCol);
      setTimeout(() => {
        handlePieceClick(bestMove.toRow, bestMove.toCol);
        gameState.aiThinking = false;
      }, gameState.isHarmonyOS ? 200 : 300);
    } else {
      gameState.aiThinking = false;
    }
  }, delay);
}

5. 游戏存档和加载 - 鸿蒙存储适配

鸿蒙端兼容 localStorage，但优化数据序列化方式，避免存储异常：

javascript

运行

// 保存游戏（鸿蒙适配版）
function saveGame() {
  const gameData = {
    board: gameState.board,
    currentPlayer: gameState.currentPlayer,
    gameStatus: gameState.gameStatus,
    moveCount: gameState.moveCount,
    moveHistory: gameState.moveHistory,
    redTime: gameState.redTime,
    blackTime: gameState.blackTime,
    aiDifficulty: gameState.aiDifficulty
  };
  
  try {
    // 鸿蒙端优化：使用try-catch包裹，避免存储权限问题
    localStorage.setItem('chinese-chess-save', JSON.stringify(gameData));
    showNotification('游戏已成功保存');
  } catch (error) {
    console.error('鸿蒙端保存游戏失败:', error);
    showNotification('游戏保存失败，请检查存储权限');
  }
}

// 加载游戏（鸿蒙适配版）
function loadGame() {
  try {
    const savedGame = localStorage.getItem('chinese-chess-save');
    
    if (!savedGame) {
      showNotification('没有找到保存的游戏');
      return;
    }
    
    const gameData = JSON.parse(savedGame);
    
    // 恢复游戏状态（原有逻辑保持不变）
    gameState.board = gameData.board;
    gameState.currentPlayer = gameData.currentPlayer;
    gameState.gameStatus = gameData.gameStatus;
    gameState.moveCount = gameData.moveCount;
    gameState.moveHistory = gameData.moveHistory;
    gameState.redTime = gameData.redTime;
    gameState.blackTime = gameData.blackTime;
    gameState.aiDifficulty = gameData.aiDifficulty;
    
    // 更新UI（原有逻辑保持不变）
    renderBoard();
    renderPieces();
    updateGameInfo();
    updateHistoryDisplay();
    difficultySelect.value = gameState.aiDifficulty;
    
    if (gameState.timerInterval) {
      clearInterval(gameState.timerInterval);
    }
    
    if (gameState.gameStatus === GAME_CONSTANTS.GAME_STATUS.PLAYING) {
      startTimer();
      if (gameState.aiMode && gameState.currentPlayer === GAME_CONSTANTS.PLAYERS.BLACK) {
        makeAIMove();
      }
    }
    
    showNotification('游戏已成功加载');
  } catch (error) {
    console.error('鸿蒙端加载游戏失败:', error);
    showNotification('加载游戏失败，存档可能已损坏');
  }
}

6. 其他核心代码

以下核心逻辑保持原有实现，鸿蒙端完全兼容：

• 棋子移动规则实现（车、马、象等七种棋子的验证函数）
• 移动评分系统（AI 决策的核心评分逻辑）
• 游戏计时系统（优化鸿蒙端时间准确性）
• 游戏结束判定（将死、困毙、超时判定）

项目结构

1. 原始 Electron 项目结构（保持不变）

plaintext

52-chinese-chess/
├── README.md           # 项目说明文档
├── main.js             # Electron主进程代码
├── package.json        # 项目配置和依赖
└── src/                # 渲染进程代码
    ├── index.html      # 应用主页面
    ├── preload.js      # 预加载脚本
    ├── renderer.js     # 渲染进程主脚本，包含游戏逻辑
    ├── style.css       # 样式文件
    └── assets/         # 资源文件（图片等）

2. 鸿蒙 PC 适配后项目结构（新增 / 调整）

plaintext

ohos_hap/                # 鸿蒙应用根目录（整合Electron项目）
├── electron/            # Electron鸿蒙核心依赖
│   └── libs/
│       └── arm64-v8a/  # 鸿蒙核心库文件（必须完整）
│           ├── libelectron.so
│           ├── libadapter.so
│           ├── libffmpeg.so
│           └── libc++_shared.so
├── web_engine/
│   └── src/
│       └── main/
│           └── resources/
│               └── resfile/
│                   └── resources/
│                       └── app/  # 原有52-chinese-chess项目代码迁移至此
│                           ├── main.js          # 已适配鸿蒙的主进程代码
│                           ├── package.json     # 适配后的依赖配置
│                           └── src/             # 原有src目录完整迁移
│                               ├── index.html
│                               ├── preload.js
│                               ├── renderer.js
│                               ├── style.css
│                               └── assets/
└── module.json5        # 鸿蒙应用配置文件（新增）

鸿蒙适配核心配置文件

1. package.json（适配调整）

json

{
  "name": "chinese-chess-harmonyos",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron .", // 原有Electron运行脚本
    "dev": "electron . --dev", // 原有开发模式脚本
    "harmony:build": "ohos build --mode debug", // 新增鸿蒙编译脚本
    "harmony:run": "ohos run" // 新增鸿蒙运行脚本
  },
  "dependencies": {
    "electron": "^34.0.0" // 升级Electron至34+（鸿蒙适配最低要求）
  },
  // 新增鸿蒙适配配置
  "harmonyos": {
    "apiVersion": 20,
    "sysCapabilities": ["windowManager", "storage", "graphics", "internet"]
  }
}

2. module.json5（鸿蒙新增配置文件）

json5

{
  "app": {
    "bundleName": "com.example.chinesechess",
    "bundleVersion": "1.0.0",
    "minAPIVersion": 20
  },
  "module": {
    "name": "chess_module",
    "type": "application",
    "srcPath": "./",
    "deviceTypes": ["pc"], // 指定为鸿蒙PC设备
    "reqSysCapabilities": [ // 仅保留必要系统能力（避免SysCap不匹配错误）
      "windowManager", // 窗口管理能力
      "storage", // 本地存储能力
      "graphics", // 图形渲染能力（Canvas依赖）
      "permission:ohos.permission.READ_USER_STORAGE", // 存储读取权限
      "permission:ohos.permission.WRITE_USER_STORAGE" // 存储写入权限
    ],
    "abilities": [
      {
        "name": "MainAbility",
        "srcPath": "./web_engine",
        "description": "中国象棋游戏主入口",
        "icon": "$media:icon",
        "label": "Chinese Chess",
        "visible": true,
        "launchType": "standard"
      }
    ]
  }
}

游戏操作指南（鸿蒙端兼容）

1. 游戏控制：
   • 点击棋子选择，再点击目标位置移动（鸿蒙端优化触摸板交互响应）
   • 有效移动位置会以高亮显示
   • 支持新游戏、重新开始、撤销走棋操作
2. 难度设置：
   • 简单：AI 有 50%（Windows/macOS）/40%（鸿蒙 PC）概率选择最佳走法
   • 中等：AI 有 75%（Windows/macOS）/80%（鸿蒙 PC）概率选择最佳走法
   • 困难：AI 总是选择最佳走法
3. 存档功能：
   • 点击保存按钮保存当前游戏状态（鸿蒙端需授予存储权限）
   • 点击加载按钮恢复之前保存的游戏
4. 计时规则：
   • 每方初始时间为 10 分钟
   • 超时自动判负（鸿蒙端优化时间计算准确性）

鸿蒙 PC 适配改造核心步骤

1. 环境准备

• 系统要求：Windows 10/11、8GB RAM 以上、20GB 可用空间
• 工具安装：
  • DevEco Studio 5.0+（安装鸿蒙 SDK API 20+）
  • Node.js 18.x+
  • Electron 34+（鸿蒙适配最低版本）

2. 项目迁移与依赖配置

1. 登录Electron 鸿蒙官方仓库
2. 下载 Electron 34 + 版本的 Release 包（.zip 格式）
3. 解压后将electron/libs/arm64-v8a/目录复制到ohos_hap/electron/libs/下（确保 4 个核心.so 库完整）
4. 将原有 52-chinese-chess 项目的所有文件（main.js、package.json、src/）复制到ohos_hap/web_engine/src/main/resources/resfile/resources/app/目录下

3. 代码改造

1. 修改 main.js：添加硬件加速禁用代码，优化窗口配置
2. 调整 package.json：升级 Electron 版本，新增鸿蒙编译 / 运行脚本
3. 创建 module.json5：配置应用信息、系统能力、设备类型
4. 优化 renderer.js：适配 Canvas 渲染、AI 性能、本地存储

4. 编译与运行

1. 在 DevEco Studio 中打开 ohos_hap 目录
2. 配置签名：进入 File → Project Structure → Signing Configs，自动生成调试签名或导入已有签名
3. 连接鸿蒙 PC 设备：启用开发者模式和 USB 调试，通过 USB Type-C 连接电脑
4. 编译运行：点击 Run 按钮或执行npm run harmony:run

5. 验证检查项

• ✅ 应用窗口正常显示，无黑屏 / 闪退
• ✅ 棋盘和棋子通过 Canvas 正常渲染，无错位
• ✅ 棋子移动规则正常，碰撞检测有效
• ✅ AI 对战功能正常，无卡顿
• ✅ 计时系统准确，无时间漂移
• ✅ 存档和加载功能正常
• ✅ 控制台无 "SysCap 不匹配" 或 "找不到.so 文件" 错误
• ✅ 响应式布局生效，窗口大小可调整

跨平台兼容性

平台	适配策略	特殊处理
Windows	标准 Electron 运行	无特殊配置
macOS	标准 Electron 运行	保留 dock 图标激活逻辑
Linux	标准 Electron 运行	确保系统依赖库完整
鸿蒙 PC	通过 Electron 鸿蒙适配层运行	1. 禁用硬件加速2. 使用特定目录结构3. 配置必要系统能力（windowManager、storage、graphics）4. 优化 Canvas 渲染和 AI 性能5. 适配本地存储权限

鸿蒙端调试技巧与常见问题解决

1. 调试技巧

• 日志查看：在 DevEco Studio 的 Log 面板中过滤 "Electron" 关键词，查看应用运行日志和错误信息
• 断点调试：在 DevEco Studio 中直接打断点，支持主进程和渲染进程调试
• 性能分析：使用 DevEco Studio 的 Performance 工具分析 AI 计算和 Canvas 渲染的性能瓶颈

2. 常见问题解决

问题现象	解决方案
"SysCap 不匹配" 错误	检查 module.json5 中的 reqSysCapabilities，仅保留必要系统能力
"找不到.so 文件" 错误	确认 arm64-v8a 目录下 4 个核心库文件（libelectron.so、libadapter.so、libffmpeg.so、libc++_shared.so）完整
窗口不显示 / 黑屏	在 main.js 中添加 app.disableHardwareAcceleration ()，检查窗口尺寸配置
Canvas 渲染错位 / 模糊	启用 imageSmoothingEnabled，优化绘图坐标计算
AI 对战卡顿	简化 AI 决策逻辑，缩短思考延迟，减少嵌套循环
存档失败	检查存储权限，使用 try-catch 包裹 localStorage 操作
计时不准确	优化计时器实现，使用 Date 对象计算时间差替代 setInterval 累加

性能优化建议（鸿蒙端专属）

1. 渲染优化：

   • 减少 Canvas 重绘频率，仅在棋子移动、窗口大小变化时重绘
   • 使用 requestAnimationFrame 替代 setTimeout 进行动画渲染
   • 优化绘图逻辑，避免重复绘制相同元素

2. AI 算法优化：

   • 简化中等 / 简单难度的 AI 决策逻辑，减少计算量
   • 限制 AI 搜索深度，避免长时间阻塞 UI 线程
   • 使用走法缓存，避免重复计算

3. 资源优化：

   • 压缩 assets 目录下的图片资源，减少加载时间
   • 精简 CSS 样式，避免复杂选择器和动画
   • 延迟加载非核心资源（如帮助文档、规则说明）

4. 内存管理：

   • 避免频繁创建大型对象（如游戏状态的深拷贝）
   • 及时清理无用定时器和事件监听
   • 使用对象池模式管理棋子渲染对象

如何运行

1. 原有 Electron 环境（Windows/macOS/Linux）

bash

运行

# 安装依赖
npm install

# 启动应用
npm start

# 开发模式（打开开发者工具）
npm start -- --dev

2. 鸿蒙 PC 环境

bash

运行

# 进入鸿蒙应用根目录
cd ohos_hap

# 安装依赖
npm install

# 编译项目
npm run harmony:build

# 连接设备后运行
npm run harmony:run

总结

本项目不仅提供了完整的中国象棋游戏实现，还详细说明了 Electron 项目迁移鸿蒙 PC 的核心流程和关键技术点。通过学习本项目，您可以掌握 Electron 桌面应用开发、游戏逻辑实现（如 AI 对战、规则引擎）以及跨平台（含鸿蒙 PC）适配的实践经验，适合 Electron 开发者和鸿蒙生态开发者参考。

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/