拼图游戏 - Electron for 鸿蒙PC项目实战案例

项目概述

这是一个基于Electron开发的拼图游戏应用，旨在为鸿蒙PC平台提供流畅的拼图游戏体验。项目实现了完整的拼图游戏功能，包括不同难度级别、图片预览、计时器、移动计数、键盘控制等特性，同时保持了界面美观和代码的可维护性。

技术要点

1. Canvas与DOM结合的游戏渲染

使用DOM元素构建拼图块，每个拼图块包含裁剪后的图片部分
通过CSS Grid布局实现拼图板的自适应排列
精确计算每个拼图块的尺寸和图片裁剪位置，确保拼图完整无缝

2. 算法实现

拼图生成算法：根据指定难度动态生成不同大小的拼图
拼图打乱算法：通过执行大量随机移动来打乱拼图，确保可解性
胜利检测算法：实时检查拼图是否恢复到正确顺序
移动合法性检查：验证用户的移动操作是否合法

3. Electron主进程与渲染进程通信

主进程负责窗口创建和应用生命周期管理
渲染进程负责游戏逻辑和UI交互
使用preload.js进行安全的API暴露

主要功能

多难度支持
- 简单模式（3×3拼图）
- 中等模式（4×4拼图）
- 困难模式（5×5拼图）
游戏体验增强
- 随机图片选择，每次游戏提供新鲜感
- 实时计时器和移动计数统计
- 图片预览功能，帮助用户记忆目标图案
- 键盘方向键控制支持
视觉效果
- 渐变背景和圆角设计
- 拼图块悬停和点击动画
- 胜利时的庆祝动画效果
- 响应式设计，适配不同屏幕尺寸

Electron特性应用

窗口管理：配置适当的窗口大小和样式，设置应用标题
预加载脚本：使用contextBridge安全地暴露API给渲染进程
进程通信：实现主进程和渲染进程之间的通信机制
应用生命周期：正确处理应用启动、窗口创建和关闭等事件

项目结构

复制代码

25-jigsaw-puzzle/
├── main.js            # Electron主进程
├── preload.js         # 预加载脚本
├── index.html         # 应用界面
├── style.css          # 样式文件
├── renderer.js        # 渲染进程逻辑
├── package.json       # 项目配置
└── README.md          # 项目说明

实现细节

1. 拼图生成与渲染

拼图生成采用二维数组存储拼图状态，每个元素代表一个拼图块的数字标识。渲染时，根据数字标识计算对应的图片裁剪位置，并动态创建DOM元素：

javascript 复制代码

// 创建拼图块
for (let row = 0; row < gameState.size; row++) {
  for (let col = 0; col < gameState.size; col++) {
    const pieceNumber = gameState.board[row][col];
    const piece = document.createElement('div');
    piece.classList.add('puzzle-piece');
    piece.dataset.row = row;
    piece.dataset.col = col;
    
    // 设置拼图块样式
    piece.style.width = `${pieceSize}px`;
    piece.style.height = `${pieceSize}px`;
    
    // 如果是空白块
    if (pieceNumber === 0) {
      piece.classList.add('empty');
    } else {
      // 创建拼图图片并设置裁剪位置
      const img = document.createElement('img');
      img.src = gameState.currentImage;
      
      // 计算图片裁剪位置
      const imgRow = Math.floor((pieceNumber - 1) / gameState.size);
      const imgCol = (pieceNumber - 1) % gameState.size;
      
      img.style.transform = `translate(-${imgCol * 100 / (gameState.size - 1)}%, -${imgRow * 100 / (gameState.size - 1)}%)`;
      img.style.width = `${gameState.size * 100}%`;
      img.style.height = `${gameState.size * 100}%`;
      
      piece.appendChild(img);
    }
    
    elements.puzzleBoard.appendChild(piece);
  }
}

2. 拼图打乱算法

为确保拼图可解，打乱算法通过执行大量随机合法移动来重新排列拼图块，而不是简单地随机打乱：

javascript 复制代码

// 打乱拼图
function shufflePuzzle() {
  // 执行大量随机移动来打乱拼图
  const moves = gameState.size * gameState.size * 100;
  
  for (let i = 0; i < moves; i++) {
    // 获取可移动的方向
    const validMoves = getValidMoves();
    if (validMoves.length > 0) {
      // 随机选择一个方向
      const move = validMoves[Math.floor(Math.random() * validMoves.length)];
      // 执行移动
      swapPieces(gameState.emptyPiece.row, gameState.emptyPiece.col, move.row, move.col);
    }
  }
  
  // 确保拼图不是已完成状态
  while (isPuzzleSolved()) {
    // 如果已完成，再执行一些随机移动
    // ...
  }
}

3. 游戏逻辑控制

游戏核心逻辑包括移动处理、胜利检测和计时器控制等：

javascript 复制代码

// 处理拼图块点击
function handlePieceClick(row, col) {
  if (!gameState.isPlaying) return;
  
  // 检查是否可以移动
  if (canMovePiece(row, col)) {
    // 执行移动
    swapPieces(gameState.emptyPiece.row, gameState.emptyPiece.col, row, col);
    
    // 更新移动次数
    gameState.moves++;
    
    // 更新UI
    renderPuzzle();
    updateGameInfo();
    
    // 检查是否完成
    if (isPuzzleSolved()) {
      handlePuzzleSolved();
    }
  }
}

4. 键盘控制支持

为提高游戏可玩性，添加了键盘方向键控制功能：

javascript 复制代码

// 处理键盘控制
function handleKeyPress(e) {
  if (!gameState.isPlaying) return;
  
  const { row, col } = gameState.emptyPiece;
  let targetRow = row;
  let targetCol = col;
  
  // 根据按键方向确定目标位置
  switch (e.key) {
    case 'ArrowUp':
      targetRow = row + 1; // 向上箭头移动空白块下方的拼图块
      break;
    case 'ArrowDown':
      targetRow = row - 1; // 向下箭头移动空白块上方的拼图块
      break;
    case 'ArrowLeft':
      targetCol = col + 1; // 向左箭头移动空白块右侧的拼图块
      break;
    case 'ArrowRight':
      targetCol = col - 1; // 向右箭头移动空白块左侧的拼图块
      break;
    default:
      return;
  }
  
  // 检查目标位置是否有效并执行移动
  // ...
}

运行方法

安装依赖：
bash 复制代码
```
npm install
```
启动应用：
bash 复制代码
```
npm start
```

学习要点

游戏开发基础：理解游戏状态管理、用户输入处理和渲染循环
DOM操作优化：如何高效地创建和更新DOM元素
Electron应用结构：学习主进程和渲染进程的职责划分
响应式设计：如何使应用在不同屏幕尺寸上都能良好显示
用户体验设计：添加适当的动画和反馈机制提升用户体验

鸿蒙PC适配改造指南

1. 环境准备

系统要求：Windows 10/11、8GB RAM以上、20GB可用空间
工具安装 ：

DevEco Studio 5.0+（安装鸿蒙SDK API 20+）
Node.js 18.x+

2. 获取Electron鸿蒙编译产物

登录Electron 鸿蒙官方仓库
下载Electron 34+版本的Release包（.zip格式）
解压到项目目录，确认electron/libs/arm64-v8a/下包含核心.so库

3. 部署应用代码

将Electron应用代码按以下目录结构放置：

plaintext 复制代码

web_engine/src/main/resources/resfile/resources/app/
├── main.js
├── package.json
└── src/
    ├── index.html
    ├── preload.js
    ├── renderer.js
    └── style.css

4. 配置与运行

打开项目：在DevEco Studio中打开ohos_hap目录
配置签名 ：

进入File → Project Structure → Signing Configs
自动生成调试签名或导入已有签名
连接设备 ：

启用鸿蒙设备开发者模式和USB调试
通过USB Type-C连接电脑
编译运行：点击Run按钮或按Shift+F10

5. 验证检查项

✅ 应用窗口正常显示
✅ 窗口大小可调整，响应式布局生效
✅ 控制台无"SysCap不匹配"或"找不到.so文件"错误
✅ 动画效果正常播放

跨平台兼容性

平台	适配策略	特殊处理
Windows	标准Electron运行	无特殊配置
macOS	标准Electron运行	保留dock图标激活逻辑
Linux	标准Electron运行	确保系统依赖库完整
鸿蒙PC	通过Electron鸿蒙适配层	禁用硬件加速，使用特定目录结构

鸿蒙开发调试技巧

1. 日志查看

在DevEco Studio的Log面板中过滤"Electron"关键词，查看应用运行日志和错误信息。

2. 常见问题解决

"SysCap不匹配"错误：检查module.json5中的reqSysCapabilities，只保留必要系统能力
"找不到.so文件"错误：确认arm64-v8a目录下四个核心库文件完整
窗口不显示：在main.js中添加app.disableHardwareAcceleration()
动画卡顿：简化CSS动画效果，减少重绘频率