项目概述

本项目是一个基于 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/

# electron # harmonyos # javascript
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

【开发者故事】这款小众穿戴应用，凭什么让7成用户天天打开 ？

avatar HarmonyOS开发者社区
cover

第04篇｜C/C++ 三方库适配 HarmonyOS：从源码编译到 HAP 内集成

avatar HarmonyOS开发者社区
cover

灯光模拟HarmonyOS应用实战-38-近光与转向灯为何不能同时表达：用正交LampState替代单一lightState

avatar HarmonyOS开发者社区