Java实战：数字华容道与石头迷阵桌面开发全解析

简介这是一份面向Java初学者与课程设计需求的数字华容道又称石头迷阵游戏实战项目源码适合正在学习Java基础、Swing界面编程或需要完成课程设计、项目实训的学生参考。资源以完整可运行的小游戏为载体帮助读者理解游戏逻辑设计、界面绘制与事件处理等核心知识点。压缩包共22个文件包含18个png图片素材用于数字方块、背景与胜利提示等界面元素、3个java源代码文件承载游戏主逻辑与界面实现以及1个iml工程配置文件整体约372KB体积轻巧便于下载与本地导入。目前已有1018人学习下载说明该项目在同类练手案例中具有一定参考价值。读者可从中获取完整的游戏实现方案、清晰的源码结构与素材组织方式并在此基础上进行二次开发或功能扩展是巩固Java面向对象编程与图形界面开发的实用练手素材。1. 数字华容道与石头迷阵一个被低估的 Java 桌面实战入口很多人第一次听到「数字华容道」这四个字脑子里浮现的是手机里那种滑动拼图小游戏觉得它简单到不值得用 Java 写一遍。但真正动手做过的人会告诉你这个判断错得离谱。数字华容道也叫 15-Puzzle和石头迷阵滑块类解谜的变体看起来只是「把方块挪到正确位置」可一旦落到代码层面你要处理的是二维数组的状态管理、鼠标点击与键盘方向键的双输入映射、打乱算法的可解性校验、以及胜利判定的边界条件。这些恰好是 Java SE 桌面开发里最核心也最容易翻车的几块内容。这篇文章面向的是想找一个「麻雀虽小五脏俱全」的 Java 实战项目练手的开发者。你可能已经学完了语法能写循环和类但还没独立完成过一个带图形界面、带状态机、带算法校验的完整程序。数字华容道就是那个合适的入口它不需要数据库、不需要网络、不需要框架一个 JDK 加一个 IDE 就能跑通但里面藏着的坑足够让你对「状态」这个词产生真正的敬畏。下面我按自己实际做这个项目的顺序把选型、实现、参数和踩坑一条条讲清楚。2. 用 Swing 还是 JavaFX桌面选型与项目骨架怎么定2.1 为什么我最终选了 Swing 而不是 JavaFX做 Java 桌面小游戏第一个绕不开的决策就是 GUI 工具包选哪个。JavaFX 在视觉上更现代支持 CSS 样式和 FXML 布局动画效果也更顺滑Swing 则是 JDK 自带的老牌方案组件模型简单直接。我选 Swing 的理由很实际这个项目的核心是逻辑而不是界面Swing 的JPanel加paintComponent重绘模型能让我把注意力集中在方块状态和移动规则上而不是花时间调样式表。另外 Swing 不依赖额外模块从 JDK 8 到 JDK 21 都能直接编译运行对新手来说少一层环境配置的折腾。如果你确实想要更漂亮的界面JavaFX 也完全可行但要注意从 JDK 11 开始 JavaFX 被移出了标准 JDK需要单独引入模块依赖。对于「先跑通再优化」的目标Swing 的启动成本更低。常见做法是先用 Swing 把逻辑跑通如果后面想换皮再把渲染层替换掉核心的棋盘模型代码可以原样复用。2.2 项目目录结构与核心类划分一个能长期维护的小项目目录结构不能随手乱放。我一般会按职责拆成三层模型层管数据视图层管绘制控制层管输入分发。下面是我实际用的结构包名用puzzle作为根src/ puzzle/ Main.java # 程序入口创建窗口 model/ Board.java # 棋盘状态二维数组、移动、判定 Tile.java # 单个方块数值、当前位置 view/ GamePanel.java # 继承 JPanel负责绘制棋盘 MainFrame.java # 继承 JFrame组装窗口 control/ GameController.java # 处理鼠标点击与键盘事件 util/ ShuffleUtil.java # 打乱算法与可解性校验这个划分的好处是Board完全不认识 Swing它只是一个纯逻辑类可以单独写单元测试。GamePanel只负责把Board的状态画出来不参与规则判断。GameController把用户的点击坐标翻译成「移动哪一行哪一列」再调用Board的方法。三层之间通过方法调用连接没有循环依赖。2.3 棋盘数据模型二维数组还是扁平数组棋盘状态用int[][]还是int[]来存是个值得想清楚的问题。二维数组int[row][col]在表达「第几行第几列」时更直观绘制和点击命中判断都方便扁平数组int[index]在计算逆序数做可解性校验时更顺手因为逆序数本身就是对一维序列定义的。我的做法是模型内部用二维数组存储需要做可解性校验时临时展平成一维校验完再还原。这样两边的好处都占上。public class Board { private final int rows; private final int cols; private int[][] grid; // 0 表示空格 private int emptyRow; private int emptyCol; public Board(int rows, int cols) { this.rows rows; this.cols cols; this.grid new int[rows][cols]; initSolved(); } // 初始化为已解状态1..N-1 顺序排列最后一个是 0 private void initSolved() { int value 1; for (int r 0; r rows; r) { for (int c 0; c cols; c) { if (r rows - 1 c cols - 1) { grid[r][c] 0; emptyRow r; emptyCol c; } else { grid[r][c] value; } } } } }这段代码里0被约定为空格这是滑块类游戏的通用做法因为 0 不会和任何有效方块数值冲突。emptyRow和emptyCol缓存空格位置避免每次移动都全盘扫描找 0。参数rows和cols决定了难度3x3 是入门4x4 是经典5x5 以上对新手来说难度陡增。我建议先用 3x3 把流程跑通再改参数试 4x4。3. 移动逻辑与打乱算法可解性校验是绕不过去的坎3.1 方块移动的判定条件与代码实现移动逻辑本身不复杂只有与空格相邻的方块才能移动移动就是交换方块和空格的位置。但「相邻」的判定要写对否则会出现斜着也能换的 bug。相邻只有上下左右四个方向用行差和列差的绝对值之和等于 1 来判断最稳妥。// 尝试移动指定位置的方块成功返回 true public boolean move(int row, int col) { // 越界直接拒绝 if (row 0 || row rows || col 0 || col cols) { return false; } // 曼哈顿距离为 1 才是相邻 int distance Math.abs(row - emptyRow) Math.abs(col - emptyCol); if (distance ! 1) { return false; } // 交换方块与空格 grid[emptyRow][emptyCol] grid[row][col]; grid[row][col] 0; emptyRow row; emptyCol col; return true; }这里用曼哈顿距离判断相邻比写四个 if 分支更简洁也不容易漏掉方向。move返回布尔值调用方可以根据返回值决定是否重绘界面、是否播放音效。注意交换后要同步更新emptyRow和emptyCol这是最容易忘的一步忘了之后空格位置就错位了后续所有移动都会乱套。3.2 随机打乱为什么不能直接 shuffle新手最容易踩的坑就是用Collections.shuffle或者随机交换若干次来打乱棋盘。这样做出来的棋盘有一半概率是无解的。数字华容道的可解性有严格的数学条件把棋盘展平成一维序列去掉空格计算逆序数。对于奇数阶棋盘3x3、5x5逆序数为偶数才可解对于偶数阶棋盘4x4逆序数加上空格所在行号从底部数的奇偶性要满足特定关系才可解。直接随机打乱等于把一半的局做成了死局玩家怎么滑都还原不了。正确做法是从已解状态出发执行大量合法的随机移动。因为每一步都是合法移动得到的局面必然可解。移动次数要足够多一般取rows * cols * 20以上太少的话打乱不充分玩家几步就还原了。public void shuffle(int steps) { Random random new Random(); int lastRow -1, lastCol -1; for (int i 0; i steps; i) { // 收集当前所有合法移动方向 Listint[] candidates new ArrayList(); int[][] dirs {{-1,0},{1,0},{0,-1},{0,1}}; for (int[] d : dirs) { int nr emptyRow d[0]; int nc emptyCol d[1]; if (nr 0 || nr rows || nc 0 || nc cols) continue; // 避免立刻反向移动回去否则打乱效率低 if (nr lastRow nc lastCol) continue; candidates.add(new int[]{nr, nc}); } if (candidates.isEmpty()) continue; int[] pick candidates.get(random.nextInt(candidates.size())); lastRow emptyRow; lastCol emptyCol; move(pick[0], pick[1]); } }steps参数控制打乱强度我一般设成rows * cols * 30。代码里记录lastRow和lastCol是为了避免「刚移过来又移回去」这种无效操作它会让打乱效率变低实际有效步数远小于循环次数。这个细节不影响正确性但影响手感。3.3 胜利判定的两种写法与性能差异胜利判定就是检查棋盘是否回到有序状态。最直观的写法是双重循环逐个比对时间复杂度 O(n²)。对于 3x3 到 5x5 的棋盘这个开销可以忽略每次移动后判一次完全没问题。但如果你想写得更优雅可以维护一个「已归位方块计数」每次移动后只更新受影响的两个位置把判定降到 O(1)。不过后者容易在打乱和重置时漏更新计数引入隐蔽 bug。我的建议是先用 O(n²) 的直白写法把功能跑通确认无误后再考虑优化不要一上来就追求 O(1)。public boolean isSolved() { int expected 1; for (int r 0; r rows; r) { for (int c 0; c cols; c) { if (r rows - 1 c cols - 1) { return grid[r][c] 0; } if (grid[r][c] ! expected) { return false; } } } return true; }注意最后一个格子必须是 0循环里提前返回的判断不能漏。这个函数在每次移动后被调用返回 true 时弹出胜利提示并停止计时。4. 界面绘制与输入处理让点击和键盘都能用4.1 paintComponent 里怎么画方块和数字Swing 的自定义绘制要重写paintComponent并且第一行必须调用super.paintComponent(g)否则会出现残影。绘制流程是先算每个格子的宽高再遍历二维数组给每个方块填色、描边、写数字。空格不画方块只留背景色。Override protected void paintComponent(Graphics g) { super.paintComponent(g); Graphics2D g2 (Graphics2D) g; // 开启抗锯齿数字边缘更平滑 g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); int tileW getWidth() / board.getCols(); int tileH getHeight() / board.getRows(); for (int r 0; r board.getRows(); r) { for (int c 0; c board.getCols(); c) { int value board.getValue(r, c); if (value 0) continue; // 空格不绘制 int x c * tileW; int y r * tileH; g2.setColor(new Color(70, 130, 180)); g2.fillRoundRect(x 4, y 4, tileW - 8, tileH - 8, 12, 12); g2.setColor(Color.WHITE); g2.setFont(new Font(SansSerif, Font.BOLD, tileH / 3)); String text String.valueOf(value); FontMetrics fm g2.getFontMetrics(); int tx x (tileW - fm.stringWidth(text)) / 2; int ty y (tileH fm.getAscent()) / 2 - 4; g2.drawString(text, tx, ty); } } }tileW和tileH用面板宽高除以行列数得到这样窗口缩放时方块会自动适配。fillRoundRect的圆角半径设 12方块看起来更柔和。字体大小取tileH / 3保证数字在不同尺寸下都清晰。文字居中用FontMetrics计算比硬编码偏移量可靠。4.2 鼠标点击坐标怎么映射到行列鼠标点击拿到的是像素坐标要换算成棋盘的行列索引。公式是col x / tileWrow y / tileH。但要注意边界如果点击位置刚好在面板边缘之外或者除出来等于行列数要拒绝。换算完调用board.move(row, col)成功就repaint()。panel.addMouseListener(new MouseAdapter() { Override public void mousePressed(MouseEvent e) { int tileW panel.getWidth() / board.getCols(); int tileH panel.getHeight() / board.getRows(); int col e.getX() / tileW; int row e.getY() / tileH; if (row 0 || row board.getRows()) return; if (col 0 || col board.getCols()) return; if (board.move(row, col)) { panel.repaint(); checkWin(); } } });这里用mousePressed而不是mouseClicked响应更快手感更好。checkWin里判断board.isSolved()成立就弹JOptionPane提示并停止计时器。4.3 键盘方向键的绑定与焦点问题键盘操作是提升体验的关键。用方向键控制「把空格旁边的方块移过来」逻辑是按上键表示把空格下方的方块往上移以此类推。绑定键盘要用InputMap和ActionMap而不是直接加KeyListener因为KeyListener要求组件有焦点焦点一丢键盘就失效这是 Swing 里经典的翻车点。InputMap im panel.getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW); ActionMap am panel.getActionMap(); im.put(KeyStroke.getKeyStroke(UP), moveUp); am.put(moveUp, new AbstractAction() { Override public void actionPerformed(ActionEvent e) { // 空格下方的方块上移即移动 (emptyRow1, emptyCol) if (board.move(board.getEmptyRow() 1, board.getEmptyCol())) { panel.repaint(); checkWin(); } } });WHEN_IN_FOCUSED_WINDOW让快捷键在整个窗口内生效不要求面板单独获得焦点。四个方向各绑一个 Action逻辑对称。注意方向键的语义容易搞反写完后一定要手动测一遍按上键应该是空格下方的方块往上滑视觉上空格往下走。5. 避坑与排查那些让我重写三遍的细节5.1 打乱后出现无解死局现象玩家把方块滑到只剩最后两个发现怎么都换不过来棋盘永远差一步。原因用了随机交换或Collections.shuffle打乱没有做可解性校验。解决改成从已解状态执行合法随机移动或者打乱后计算逆序数校验不满足就重新打乱。我现在的习惯是直接用合法移动法从根上杜绝这个问题。5.2 窗口缩放后方块错位或数字模糊现象拖动窗口边缘改变大小方块位置和点击区域对不上数字也糊成一团。原因绘制时用了固定的方块尺寸没有根据面板实时宽高计算或者没开抗锯齿。解决在paintComponent里每次都用getWidth()和getHeight()重新算tileW和tileH并开启KEY_ANTIALIASING。点击映射也要用同一套实时尺寸保证绘制和命中一致。5.3 键盘方向键时灵时不灵现象点一下鼠标后方向键能用切到别的窗口再切回来就失效了。原因用了KeyListener它依赖组件焦点焦点丢失后收不到事件。解决改用InputMap加ActionMap绑定条件设为WHEN_IN_FOCUSED_WINDOW。这个改动很小但能彻底解决焦点玄学。5.4 计时器没停导致胜利后还在走现象弹出胜利提示后界面上的计时还在增加。原因checkWin里只弹了对话框没有停止javax.swing.Timer。解决在判定胜利的分支里调用timer.stop()并把步数计数也冻结。如果用了多个计时器要确保每个都停掉别只停一个。5.5 移动后界面不刷新现象逻辑上移动成功了但画面没变要拖动窗口才更新。原因改了模型数据但没调用repaint()或者repaint调在了错误的组件上。解决每次board.move返回 true 后立刻对绘制面板调用repaint()。如果是在子线程里改的数据要用SwingUtilities.invokeLater切回事件分发线程再重绘。6. 从能跑到好用难度分级与状态持久化的进阶做法把基本功能跑通只是第一步真正让这个项目拿得出手的是后面这些进阶处理。我按自己迭代的顺序讲三个方向。第一个是难度分级。3x3、4x4、5x5 不应该只是改个构造参数而应该做成菜单可切换。切换时要做三件事重建Board、重置计时和步数、重新打乱。这里有个容易忽略的点切换难度后之前绑定的键盘 Action 仍然有效但board引用要更新否则方向键还在操作旧棋盘。我的做法是把board作为GameController的成员切换时替换引用Action 内部通过controller.getBoard()拿当前棋盘而不是持有旧引用。第二个是最佳成绩的持久化。用java.util.prefs.Preferences按难度分别存最少步数和最短时间不需要数据库也不需要文件读写。键名用best_steps_3x3这种格式读取时做空值兜底。每次胜利后比较并更新界面上用JLabel展示。这个功能代码量很小但让项目从「练习」变成了「能玩」。第三个是动画过渡。方块瞬移会显得生硬可以用Timer做插值动画记录方块移动前后的像素坐标在 100 到 150 毫秒内分若干帧插值绘制。这里的关键是动画期间要锁住输入否则玩家连点会导致状态错乱。我一般用一个boolean animating标志动画开始时置 true结束时置 false输入处理里先检查这个标志。// 最佳成绩持久化的核心逻辑 Preferences prefs Preferences.userNodeForPackage(Board.class); String key best_steps_ rows x cols; int best prefs.getInt(key, Integer.MAX_VALUE); if (currentSteps best) { prefs.putInt(key, currentSteps); // 注意Preferences 的写入是异步的不必手动 flush }这段代码里Preferences.userNodeForPackage会按类所在包生成一个节点路径不同项目互不干扰。getInt的第二个参数是默认值第一次运行时返回Integer.MAX_VALUE任何真实步数都会小于它所以第一次成绩必然被记录。putInt之后不需要手动flush系统会在合适时机落盘但如果你在测试中需要立刻读到可以调flush()强制同步。最后说一个我自己的教训这个项目我前后重写了三遍前两遍都栽在「状态不一致」上——模型改了界面没改或者界面以为改了模型其实没改。后来我定了一条规矩任何修改棋盘状态的操作必须走Board的公开方法并且方法返回布尔值表示是否真的改变了状态调用方根据返回值决定是否重绘。这条规矩看起来笨但它把「什么时候该刷新」这个判断从人脑转移到了代码里省掉了大量排查时间。希望帮到你。本文还有配套的精品资源点击获取