React Native鸿蒙跨平台推箱子游戏：地图建模与核心逻辑实现

1. 把推箱子题目拆开先看清这到底是个什么需求“React Native 鸿蒙跨平台实现推箱子游戏完成玩家移动与箱子推动当所有箱子都被推到目标位置时玩家获胜。”这个标题乍看是一整句需求描述拆开其实是一道特别经典的游戏编程题在地图网格里控制一个角色移动角色碰到箱子就把箱子往前推箱子不能穿墙也不能同时推两个最后判断每个目标点是否都被箱子占住。核心点其实就三个玩家移动、箱子推动、胜利判定。听起来简单但真正落地时会牵扯到坐标系设计、碰撞检测、地图数据建模、状态同步、UI渲染、跨平台适配。尤其是当目标平台变成鸿蒙设备又不希望只做一个单平台 Demo 时React Native 就成了一个很实际的选项游戏逻辑跑在 JavaScript/TypeScript 一层UI 用 React 组件描述底层鸿蒙原生控件负责渲染渲染一套代码在多个平台复用。这不只是省工作量更重要的是让“游戏规则”和“平台差异”彻底解耦后续维护时不需要把一份逻辑复制多份。这篇文章我会把这个推箱子项目从需求拆解到完整实现全部过一遍。整个项目适合有一定 React Native 基础、想试试游戏类应用的人也适合刚接触鸿蒙跨平台开发的读者。你跟着把地图数据、移动判断、界面渲染、事件处理这几块搭起来就能得到一个小而完整的可玩 GameDemo再往里面加关卡、加撤销、加音效都是水到渠成的事。2. 整体设计与地图数据建模2.1 用二维数组表达地图是推箱子最朴素的解法推箱子的地图天然就是二维网格所以用二维数组表达是最直观的。一个典型的关卡可以这样描述每一格可能是墙、空地、箱子、玩家、目标点而目标点可以被箱子覆盖也可以被玩家站上去这就需要一套数字编码来处理叠加状态。我最终采用的是“静态底图 动态棋子”两个层次底图只存三种元素墙、空地、目标点。动态层存玩家位置和所有箱子位置。export const TILE { EMPTY: 0, WALL: 1, TARGET: 2, BOX: 3, PLAYER: 4, } as const; export interface Point { row: number; col: number; } export interface GameState { player: Point; boxes: Point[]; }这样做的最大好处是渲染时可以通过“底图单元格 当前是否有箱子 当前是否有玩家”来推导出最终画面而不需要维护一堆“箱子已经在目标上”“玩家已经在目标上”的混合状态。否则到后面判断胜利、重置关卡、做撤销时状态组合会爆炸。2.2 一个最小可玩的关卡长什么样我准备了一个 5x5 的基础关卡格子的具体含义如下export const LEVEL_1 [ [1, 1, 1, 1, 1], [1, 0, 0, 0, 1], [1, 0, 4, 0, 1], [1, 0, 3, 2, 1], [1, 1, 1, 1, 1], ];数字对应关系1 是墙0 是空地2 是目标点4 是玩家3 是箱子。这一关里玩家只需要向右推一步就能把箱子推上右边的目标点。实际项目中关卡数据不会直接拿来当运行状态因为玩家和箱子是会移动的。所以我写了一个解析函数把 LEVEL_1 这种带初始棋子的二维数组拆成“底图”和“初始状态”两份干净的数据export function parseLevel(source: number[][]) { const baseMap source.map(row row.map(cell cell TILE.WALL || cell TILE.TARGET ? cell : TILE.EMPTY ) ); const boxes: Point[] []; let player: Point | null null; source.forEach((row, r) { row.forEach((cell, c) { if (cell TILE.PLAYER) { player { row: r, col: c }; } if (cell TILE.BOX) { boxes.push({ row: r, col: c }); } }); }); if (!player) { throw new Error(地图里至少需要一个玩家); } return { baseMap, initialState: { player, boxes }, }; }思路不复杂底图里只保留墙和目标点其余格子都转成空地箱子坐标收集到数组玩家坐标单独存。以后做多关卡时只需要继续往数组里塞数据解析逻辑完全不用动。2.3 把游戏引擎与 React 组件拆开比想象中更重要很多人写小游戏时会直接把地图 state 塞进 React 组件里然后在按钮的 onPress 里直接改数组。这个做法在功能上跑得通但很容易让代码越来越难维护。我的建议是把“移动逻辑”写成纯函数组件只负责调用它、渲染结果。纯函数的意思是给一个旧状态和移动方向返回一个新状态不直接修改旧状态里的数组。这样做有实打实的好处逻辑不依赖 React不依赖鸿蒙或 iOS 的 API可以随意做单元测试撤销、重做、自动求解这类功能都能建立在“状态快照”上以后如果要把游戏逻辑搬到别的界面框架里可以直接复用。React 组件里的状态就保持单一来源统一用useState管理一个GameState对象。后面你会在移动函数里看到每次操作后都返回一个新对象React 才能正确触发重渲染。3. 核心逻辑实现移动、推箱、胜负判断3.1 玩家移动与越界、撞墙判断玩家移动是所有逻辑的第一步。这里我采用 row/col 作为坐标row 表示第几行col 表示第几列和屏幕坐标的 x/y 并不一样。向上移动时 row 减 1向下移动时 row 加 1向左移动 col 减 1向右移动 col 加 1。export function moveState( state: GameState, baseMap: number[][], dx: number, dy: number ): GameState { const { player, boxes } state; const nr player.row dy; const nc player.col dx; const rows baseMap.length; const cols baseMap[0].length; if (nr 0 || nr rows || nc 0 || nc cols) { return state; } if (baseMap[nr][nc] TILE.WALL) { return state; } const boxIndex boxes.findIndex(b b.row nr b.col nc); if (boxIndex -1) { return { ...state, player: { row: nr, col: nc }, }; } // 下面是推箱子的分支 }很多人会忽略边界判断直接把baseMap[nr][nc]拿出来比较结果玩家走到地图边缘时nr或nc超出数组范围轻则取到 undefined重则直接报错。先判断行列坐标是否越界再判断是墙还是空地这是一个非常基础的习惯。为什么碰到箱子时不直接让玩家穿过去因为推箱子的规则就是玩家面前如果有箱子玩家不能占据箱子所在格只能让箱子往更前方滚动一格。如果箱子前方也是墙或者被另一个箱子挡住那这一步移动就不合法玩家停在原地。3.2 箱子的推动与连续推动细节箱子推动是整个游戏里最容易写错的地方。箱子的新位置等于“玩家移动方向再往前一格”所以要用nr dy和nc dx计算。此时要判断两个条件箱子前方是不是墙箱子前方有没有其他箱子。const nbr nr dy; const nbc nc dx; const beyondIsWall baseMap[nbr]?.[nbc] TILE.WALL; const beyondHasBox boxes.some(b b.row nbr b.col nbc); const beyondOutOfBounds nbr 0 || nbr rows || nbc 0 || nbc cols; if (beyondOutOfBounds || beyondIsWall || beyondHasBox) { return state; } const nextBoxes boxes.map((box, index) index boxIndex ? { row: nbr, col: nbc } : box ); return { player: { row: nr, col: nc }, boxes: nextBoxes, }; }这里有个特别容易忽略的点箱子可能正站在目标点上。从视觉上看你可能会用“箱子在目标点”和“箱子不在目标点”两种状态分别渲染但在逻辑层并没必要区分。底图里的目标点一直都在箱子数组里记录的是它的坐标。我只需要在渲染时判断“这个坐标在底图里是不是 TARGET”是就画成“箱子目标点叠加样式”不是就画成普通箱子。这种设计避免了推箱子时反复改写底图的状态也避免了“箱子离开目标点后目标点消失”的经典 Bug。你只需要保证箱子位置的底图信息永远不变箱子位置本身是可变的。如果箱子前方是目标点我并不会把它特殊标记成一个“已到位箱子”因为箱子数组里的坐标已经说明一切。胜利时只需要逐个比对箱子坐标对应的底图是不是 TARGET。3.3 胜利判定不是“没有箱子失败”而是“每个箱子都在目标点上”胜利条件听起来很直接所有箱子都被推到目标位置。实现上写成export function checkWin(boxes: Point[], baseMap: number[][]): boolean { return boxes.every(box { const cell baseMap[box.row]?.[box.col]; return cell TILE.TARGET; }); }这里我推荐用every语义和需求完全一致只要有一个箱子不在目标点就返回 false。有些人会反过来写“不存在不在目标点上的箱子”逻辑上等价但可读性差很多。需要特别提醒的是初始地图里箱子的数量和目标点的数量必须相等。如果箱数少于目标数就算所有箱子都放在目标点上仍然有空目标点游戏永远无法获胜如果箱数多于目标数就永远有多余箱子推不上目标。所以多关卡里最好在解析时加一个校验比如统计TARGET和BOX的数量不一致就直接报警避免玩家卡死在不可能通关的关卡里。3.4 React 状态更新方式为什么一定要用函数式更新React 的状态更新是异步的而且同一时刻多次点击时game这个闭包变量未必能拿到最新值。比如快速连按两次方向键如果直接在 onPress 里写const next moveState(game, baseMap, dx, dy); setGame(next);第二次点击时拿到的game可能还是旧状态结果两次移动基于同一份旧数据计算最终只生效一步玩家会觉得按键“失灵”。正确做法是用函数式更新让 React 保证传入的一定是最新状态function move(dx: number, dy: number) { setGame(prev moveState(prev, baseMap, dx, dy)); }这样无论点击多快每次更新都建立在最新状态之上。步骤计数也可以通过比较函数返回值是否和旧状态是同一个引用来判断是否算作有效移动function move(dx: number, dy: number) { let moved false; setGame(prev { const next moveState(prev, baseMap, dx, dy); if (next prev) { return prev; } moved true; return next; }); if (moved) { setSteps(prev prev 1); } }注意moveState在非法移动时直接返回原对象所以判断next prev就能区分有效移动和无效移动不会给玩家的步数多加计数。4. React Native 界面搭建从地图渲染到操作交互4.1 准备组件状态和初始化数据游戏界面需要一个初始关卡用useState存当前游戏状态。为了避免每次渲染都重新解析关卡我习惯用useMemo缓存初始数据import React, { useEffect, useMemo, useState } from react; import { View, Text, TouchableOpacity, StyleSheet } from react-native; const levelData useMemo(() parseLevel(LEVEL_1), []); const [game, setGame] useState(levelData.initialState); const [steps, setSteps] useState(0); const [won, setWon] useState(false); useEffect(() { if (checkWin(game.boxes, levelData.baseMap)) { setWon(true); } }, [game.boxes]);won状态没有塞进game对象里是因为它属于界面层的东西。核心纯函数只负责判断“这一堆箱子坐标是否全部命中目标点”至于要不要弹窗、要不要放礼花那是 UI 层需要考虑的。这样职责更清楚也方便以后接语音提示、震动反馈等平台能力。重置操作也很简单重新生成一份初始状态同时把步数和胜利状态清空。function resetGame() { setGame({ player: { ...levelData.initialState.player }, boxes: levelData.initialState.boxes.map(box ({ ...box })), }); setSteps(0); setWon(false); }这里为什么要复制一份对象因为useState里的对象如果直接复用重置后可能和初始状态对象共享引用后续一旦误操作修改了某个字段初始数据也被污染。浅拷贝一层虽小却是避免诡异 Bug 的好习惯。4.2 把二维数组渲染成游戏棋盘棋盘渲染本质上就是两层循环。外层遍历行内层遍历列每格渲染一个View再根据格子的类型决定背景样式。function renderCell(row: number, col: number) { const hasBox game.boxes.some(b b.row row b.col col); const isPlayer game.player.row row game.player.col col; const base levelData.baseMap[row][col]; let cellStyle styles.empty; if (base TILE.WALL) { cellStyle styles.wall; } else if (hasBox) { cellStyle base TILE.TARGET ? styles.boxOnTarget : styles.box; } else if (isPlayer) { cellStyle base TILE.TARGET ? styles.playerOnTarget : styles.player; } else if (base TILE.TARGET) { cellStyle styles.target; } return View key{${row}-${col}} style{[styles.cell, cellStyle]} /; } View style{styles.board} {levelData.baseMap.map((rowData, row) ( View style{styles.row} key{row} {rowData.map((_, col) renderCell(row, col))} /View ))} /View样式上我习惯把格子做成固定边长并让棋盘整体居中const styles StyleSheet.create({ board: { alignItems: center, }, row: { flexDirection: row, }, cell: { width: 44, height: 44, }, empty: { backgroundColor: #f0efe4, }, wall: { backgroundColor: #555b66, }, target: { backgroundColor: #faf3c0, borderWidth: 2, borderColor: #d9b48f, }, box: { backgroundColor: #c8935a, }, boxOnTarget: { backgroundColor: #7fae5f, }, player: { backgroundColor: #3f8fc9, }, playerOnTarget: { backgroundColor: #2d6fa8, }, });用颜色区分不同元素只是最基础方案。想要更好看也可以把每个格子替换成 Image 或 Icon但核心渲染逻辑都是一样的根据当前格子的“底图类型 动态层状态”选择资源。4.3 方向按钮与手势滑动的实现小游戏在手机上最常见的交互有两种点按方向键、滑动屏幕。方向键最稳实现也简单四个按钮按行列方向触发移动View style{styles.controls} View style{styles.controlRow} TouchableOpacity style{styles.button} onPress{() move(0, -1)} Text style{styles.buttonText}上/Text /TouchableOpacity /View View style{styles.controlRow} TouchableOpacity style{styles.button} onPress{() move(-1, 0)} Text style{styles.buttonText}左/Text /TouchableOpacity TouchableOpacity style{styles.button} onPress{() move(1, 0)} Text style{styles.buttonText}右/Text /TouchableOpacity /View View style{styles.controlRow} TouchableOpacity style{styles.button} onPress{() move(0, 1)} Text style{styles.buttonText}下/Text /TouchableOpacity /View /View按钮点击区域尽量做大一些比如 64x64 以上减少误触。鸿蒙设备上有不少全面屏机型屏幕边缘容易触发系统手势所以底部控制区要留足安全距离。如果还想支持滑动操作React Native 的PanResponder是很直接的选择const panResponder useRef( PanResponder.create({ onPanResponderRelease: (_, gestureState) { const dx gestureState.dx; const dy gestureState.dy; if (Math.abs(dx) 30 Math.abs(dy) 30) { return; } if (Math.abs(dx) Math.abs(dy)) { move(dx 0 ? 1 : -1, 0); } else { move(0, dy 0 ? 1 : -1); } }, }) ).current;滑动判断的要点是先设定一个阈值避免普通点击被误判成滑动再比较横向纵向位移的绝对值取更明显的一个方向作为移动方向。这套逻辑本质上和推箱子无关是一种通用的手势方向识别以后在小游戏、轮播图、翻页组件里都能复用。把panResponder.panHandlers展开到棋盘容器上滑动和按钮就能同时生效。要注意的是容器层级不要让 PanResponder 拦截掉子层按钮的点击通常把panHandlers放在棋盘区域外层的 View 上更安全。4.4 步数、胜利提示和重置按钮游戏界面上还需要几个简单的状态元素。步数可以用一个文本显示胜利提示则在won为 true 时显示。这个小东西虽然不起眼但体验上的差别很大玩家推箱子时不知道自己走了多少步就会缺少目标和成就感。View style{styles.statusBar} Text style{styles.statusText}步数{steps}/Text {won ? Text style{styles.winText}恭喜通关/Text : null} TouchableOpacity style{styles.resetButton} onPress{resetGame} Text style{styles.resetText}重置/Text /TouchableOpacity /View胜利弹窗、通关后自动进入下一关、播放音效这些都可以基于won这个状态继续扩展。短期内不需要做得太复杂先把核心玩法闭环跑通。5. 鸿蒙跨平台适配与常见坑5.1 跨平台运行时的界面差异处理React Native 在鸿蒙生态里的核心优势是JavaScript 逻辑和 React 组件描述能直接复用。比如推箱子里的数组遍历、React state、TouchableOpacity 交互在 iOS、Android、鸿蒙设备上行为基本一致。真正有差异的是平台视觉特性。鸿蒙设备目前有不少大屏、折叠屏机型屏幕比例和 iOS/Android 主流机型并不完全一样。如果格子宽度写死 44在大屏上会显得棋盘偏小在小屏上又可能被刘海、挖孔等区域遮挡。所以我更推荐用动态尺寸import { useWindowDimensions } from react-native; const screenWidth useWindowDimensions().width; const boardSize Math.min(screenWidth - 32, 360); const cellSize boardSize / levelData.baseMap[0].length;用useWindowDimensions拿到实时窗口尺寸后格子大小根据列数动态计算。这样横竖屏切换时棋盘也能自动适配。计算时记住留出左右边距别把棋盘顶到屏幕边缘否则全面屏的圆角区域会挡住一部分格子。安全区域也要注意。底部控制按钮如果和系统手势区域重叠玩家操作时很容易触发返回手势。可以给整个页面套一个安全区容器或者给底部控制区加动态 padding。具体写法取决于你在用的导航组件但核心思路是一样的让可交互元素避开系统手势热区。5.2 触摸与按钮交互在鸿蒙设备上的注意点鸿蒙设备上的触摸事件和 React Native 标准触摸体系整体兼容但我在实际测试中遇到过几个值得注意的现象按钮点击区域太小会偶尔没反应。系统级触摸目标建议至少 44x44实际项目里我一般做成 64x64 以上。快速连续点按时如果按钮没有做防抖可能一次点按被识别成两次。这在推箱子里反而可以通过函数式更新规避因为移动逻辑本身是幂等的。PanResponder 和 ScrollView 同时存在时会抢手势所以游戏界面尽量不要包一层可滚动容器除非你明确设置了手势优先级。另外在鸿蒙设备上如果按钮用了比较特殊的字体个别汉字可能显示宽度不一致导致按钮里的“上、下、左、右”居中不准确。稳妥的做法是给按钮文本固定宽度或者把文字单独居中而不是依赖按钮的 padding 自动撑开。5.3 常见问题与排查速查表我把实际开发里最常踩的坑整理成一个速查表你可以直接对照检查现象可能原因处理方法玩家移动到地图边缘后画面卡死或报错没有做边界判断访问了不存在的数组下标移动前先检查 nr/nc 是否在合法范围玩家能直接走到箱子上没有检测目标格是否已被箱子占用在普通移动分支前先查 boxes.findIndex箱子被推出地图边界只检测箱子前方是墙没检测越界推箱分支里对箱子新坐标做同样的边界检查两个箱子叠在一起推箱时只检查了墙没检查箱子的新坐标有没有被其他箱子占位用 boxes.some 检查箱子新坐标通关条件永远不满足目标点数量和箱子数量不一致解析关卡时单独统计 TARGET 和 BOX 数量快速连按方向键只移动一次使用了闭包中的旧 game 状态改成 setGame(prev moveState(prev, ...))重置后箱子位置错乱重置时直接复用了初始对象的引用对 player 和每个 box 做浅拷贝鸿蒙端棋盘被状态栏或挖孔遮挡布局没有考虑安全区域使用安全区组件或动态 padding滑动屏幕时方向判断不对dx/dy 的阈值或方向判断逻辑写反确认 row 增加方向与 dy 正负的对应关系还有一个很多人会忽视的细节如果状态更新后需要立刻读取最新game值做一些操作不要直接写在 setGame 后面因为此时 state 还没更新完。正确的方式是放到useEffect里监听game变化或者在函数式更新内部处理。这个坑在 React 里很经典在 React Native 里也一样无论目标平台是 iOS、Android 还是鸿蒙都要遵循同一套状态更新规则。5.4 关于鸿蒙适配的一点实际体会这个项目选择 React Native 跨平台方案不是因为鸿蒙原生开发不行而是因为推箱子这种逻辑密度高、平台交互少的应用用跨端方案能把开发效率拉满。纯游戏逻辑写一次UI 组件复用真正需要针对鸿蒙做调整的可能只是屏幕适配、触摸热区、安全边距这些外围细节。如果你后续想把游戏做得更有“鸿蒙味”可以考虑把界面中的按钮替换成系统组件风格或者接入震动反馈、系统分享等能力。这些扩展通常不影响已有的移动和推箱核心逻辑。我个人在实际操作中最有体会的一点是永远不要把“判断箱子是否到位”写成“箱子坐标等于目标坐标数组里某一个”这样的强匹配。因为只要关卡地图稍大一点这种写法会越改越乱。基于底图判断目标点的方式在任何复杂度下都稳定这才是推箱子逻辑层的正确打开方式。另外项目里如果打算加多关卡建议把关卡数据从代码里拆出去单独放成一个 JSON 或 TS 常量文件解析逻辑保持单一。后续加关卡、做编辑器、测试自动求解都会顺手很多。推箱子这种小游戏虽然体量不大但把数据、逻辑、UI 三层边界划清楚之后它应对后续扩展的能力会远超你的预期。