Java Swing数独实战：从GUI布局到输入校验与撤销机制

简介：这是一份面向Java初学者与高校课程设计学生的Swing桌面应用实践项目，聚焦数独游戏逻辑实现与GUI交互开发，帮助学习者掌握事件驱动编程、布局管理、文件资源加载及MVC思想雏形。资源包含完整可运行工程，共21个文件：6个Java源码（涵盖主窗体、数独生成器、校验逻辑与难度控制等核心模块），5个XML配置文件（用于界面资源绑定与偏好设置），3个PNG图标及ICO格式程序图标，辅以IDEA与MyEclipse兼容的.project、.iml、.classpath等工程元数据文件，整体压缩包仅81KB，轻量易导入。已有1005人学习下载，适合Java课程设计参考、Swing组件实战练习或小型GUI项目快速上手。读者可直接编译运行，深入理解数独算法（如回溯生成）、Swing线程安全机制、资源路径加载规范，并通过清晰分层的src目录结构（含hlc子包）体会基础工程组织方式。

1. 为什么一个“Java课程设计作业”能成为 Swing 实战的黄金练手项目？

数独小游戏，表面看只是个填数字的逻辑游戏，但落到 Java 课程设计层面，它恰恰是 Swing GUI 开发最扎实、最不取巧的落点：没有花哨动画，却要精准控制 9×9 网格的焦点、输入校验、状态回滚；不依赖网络或数据库，却必须把规则引擎（唯一性、宫格约束）、撤销重做、难度生成、解题验证全链路闭环；代码量可控（2000–4000 行），但每一处都暴露 Swing 的核心机制——事件分发线程（EDT）调度、布局管理器协作、自定义组件绘制、键盘快捷键绑定。我带过几届某高校的 Java 实训课，发现学生交上来“计算器”“记事本”类作业，十有八九是 Ctrl+C/V 拼凑的；而真正从零写完一个可玩、可调、可 debug 的数独，基本就跨过了 Swing 的“黑匣子恐惧期”。它不追求炫技，但能把JFrame到JButton再到KeyListener和DocumentFilter的协作逻辑，一寸寸钉进肌肉记忆。如果你正卡在“学了 Swing 却写不出完整交互”的阶段，这个项目不是玩具，是照出你真实工程能力的镜子。

2. 从零搭起主窗口：用 BorderLayout + GridLayout 构建可伸缩的数独棋盘

数独界面看似简单，实则对布局稳定性要求极高：9×9 单元格需等宽等高，顶部工具栏要固定高度，底部状态栏不能被挤压，且整个窗口缩放时，棋盘应均匀拉伸而非变形。Swing 原生布局中，BorderLayout作主容器、GridLayout嵌套构建棋盘，是最轻量又最可控的组合。常见误区是直接用GridBagLayout过度设计，反而因权重配置错误导致单元格错位。

2.1 主框架初始化与 BorderLayout 分区

public class SudokuGame extends JFrame { private JPanel boardPanel; // 棋盘区域 private JPanel controlPanel; // 控制按钮区 private JLabel statusLabel; // 状态提示 public SudokuGame() { setTitle("Java 数独小游戏"); setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); setLayout(new BorderLayout()); // 主布局设为 BorderLayout // 初始化各区域 initBoardPanel(); initControlPanel(); initStatusPanel(); // 按 BorderLayout 规则添加 add(boardPanel, BorderLayout.CENTER); // 棋盘占满中央，自动拉伸 add(controlPanel, BorderLayout.NORTH); // 控制区置顶，固定高度 add(statusLabel, BorderLayout.SOUTH); // 状态栏置底，固定高度 pack(); // 初始尺寸自适应内容 setLocationRelativeTo(null); // 居中显示 setResizable(true); // 允许用户缩放窗口 } }

提示：pack()是关键一步。若先setSize()再add()，会导致BorderLayout分区失效；必须让容器先完成组件添加，再由pack()计算最小合理尺寸。后续用户缩放时，CENTER区域会自动填充剩余空间，而NORTH/SOUTH区域保持自身preferredSize不变。

2.2 用三层 GridLayout 嵌套实现“宫格感”视觉分割

纯GridLayout(9,9)虽能排布单元格，但无法体现数独“3×3 宫格”的视觉边界。解决方案是嵌套三层：外层GridLayout(3,3)划分九宫，中层每个宫格内再用GridLayout(3,3)排布小格，内层每个小格用JTextField并设置边框。这样既保证逻辑网格一致，又通过TitledBorder实现视觉分组。

private void initBoardPanel() { boardPanel = new JPanel(new GridLayout(3, 3, 2, 2)); // 外层：3×3 宫格，间隙2px boardPanel.setBorder(BorderFactory.createEmptyBorder(10, 10, 10, 10)); // 内边距 // 创建9个宫格面板 for (int i = 0; i < 9; i++) { JPanel subPanel = new JPanel(new GridLayout(3, 3, 1, 1)); // 中层：每宫3×3小格，间隙1px subPanel.setBorder(BorderFactory.createTitledBorder( BorderFactory.createLineBorder(Color.GRAY, 2), "宫 " + (i + 1) )); // 可选：加标题，调试时直观 // 向每个宫格添加9个 JTextField for (int j = 0; j < 9; j++) { JTextField cell = new JTextField(); cell.setFont(new Font("Arial", Font.BOLD, 18)); cell.setHorizontalAlignment(JTextField.CENTER); cell.setPreferredSize(new Dimension(40, 40)); // 设定基础尺寸，避免缩放失真 cell.setDocument(new NumberOnlyDocument()); // 关键：限制只输数字，见 3.2 节 cell.addKeyListener(new CellKeyListener()); // 键盘监听，见 4.1 节 subPanel.add(cell); } boardPanel.add(subPanel); } }

参数说明：

• GridLayout(3,3,2,2)的2,2是水平/垂直间隙，值太小（如0）会导致宫格线粘连，太大（如5）则浪费空间；2px是兼顾清晰度与紧凑性的经验值。
• setPreferredSize(new Dimension(40,40))必须显式设置。Swing 默认JTextField尺寸极小，若依赖pack()自动计算，缩放时各单元格会因内容不同（空 vs 数字）而高度不一，破坏网格对齐。
• TitledBorder在正式发布版中建议移除（仅调试用），否则会遮挡部分单元格；生产环境改用LineBorder配合setBorderPainted(false)更干净。

3. 让每个格子“懂规则”：自定义 Document + 输入校验的底层控制

Swing 中，JTextField的输入控制有两个层级：表层是KeyListener拦截按键，底层是Document拦截字符插入。前者易受焦点切换、粘贴绕过；后者才是真正的“守门人”。数独要求：只能输入 1–9 数字、空格清空、禁止字母/符号/多位数。用PlainDocument子类重写insertString()是最可靠方案。

3.1 编写 NumberOnlyDocument：拦截非法字符与长度超限

class NumberOnlyDocument extends PlainDocument { @Override public void insertString(int offset, String str, AttributeSet attr) throws BadLocationException { if (str == null) return; // 1. 只允许数字、空格、退格、删除键 for (char c : str.toCharArray()) { if (!Character.isDigit(c) && c != ' ' && c != '\b' && c != '\u007F') { return; // 直接丢弃非法字符 } } // 2. 防止输入多位数：当前文本非空时，只允许单字符替换（即覆盖模式） String currentText = getText(0, getLength()); if (currentText.length() > 0 && str.length() > 1) { // 用户粘贴多位数？只取第一个字符 super.insertString(offset, str.substring(0, 1), attr); return; } // 3. 允许空格清空（长度为0时插入空格视为清空） if (str.equals(" ") && currentText.length() > 0) { remove(0, currentText.length()); // 清空现有内容 return; } // 4. 正常插入：数字或空格 super.insertString(offset, str, attr); } }

逻辑说明：

• insertString()是Document的核心钩子，所有文本变更（键入、粘贴、程序设置）必经此方法。
• 第 2 步是血泪经验：初版未限制粘贴，用户粘贴"123"导致单元格显示"123"，后续校验直接崩溃。强制截断为单字符，既防崩又符合数独“单格单数”直觉。
• 第 3 步处理空格逻辑：当格子已有数字时，按空格应清空而非输入空格（空格在数独中无意义），这是用户预期行为。

3.2 绑定 Document 并实时触发规则校验

光拦截输入不够，还需在每次合法输入后，立即检查该格是否违反数独规则（行、列、宫格重复）。将校验逻辑封装为独立方法，并在Document插入成功后调用：

// 在 NumberOnlyDocument 类中添加回调接口 public interface ValidationCallback { void onCellChanged(int row, int col, char newValue); } // 修改 insertString 方法末尾： super.insertString(offset, str, attr); if (callback != null && str.length() > 0) { // 解析当前格子在 9×9 中的行列索引（需外部传入 row/col） callback.onCellChanged(currentRow, currentCol, str.charAt(0)); }

注意：currentRow/currentCol需在创建NumberOnlyDocument实例时传入，或通过JTextField的putClientProperty()存储。这是 Swing 中“组件与数据绑定”的常用技巧，避免全局变量污染。

4. 键盘操作闭环：方向键移动 + 回车确认 + ESC 撤销的完整交互链

鼠标点击选格效率低，专业数独玩家依赖键盘。一个完整的键盘流应支持：方向键（↑↓←→）切换焦点、数字键（1–9）填数、Backspace/Delete 清空、Enter 提交（用于标记候选数）、ESC 撤销上一步。这要求KeyListener精准捕获事件，并与FocusTraversalPolicy协同。

4.1 为所有单元格注册统一 KeyListener

class CellKeyListener extends KeyAdapter { @Override public void keyPressed(KeyEvent e) { JTextField source = (JTextField) e.getSource(); int keyCode = e.getKeyCode(); // 1. 方向键：移动焦点 if (keyCode == KeyEvent.VK_UP || keyCode == KeyEvent.VK_DOWN || keyCode == KeyEvent.VK_LEFT || keyCode == KeyEvent.VK_RIGHT) { moveFocus(source, keyCode); e.consume(); // 阻止默认行为（如向上滚动） return; } // 2. 数字键：填入数字（忽略 NumPad，统一用主键盘） if (keyCode >= KeyEvent.VK_1 && keyCode <= KeyEvent.VK_9) { char digit = (char) ('0' + (keyCode - KeyEvent.VK_1 + 1)); fillCell(source, digit); e.consume(); return; } // 3. Backspace/Delete：清空 if (keyCode == KeyEvent.VK_BACK_SPACE || keyCode == KeyEvent.VK_DELETE) { clearCell(source); e.consume(); return; } // 4. Enter：标记候选（此处简化为填数，实际可扩展） if (keyCode == KeyEvent.VK_ENTER) { submitCell(source); e.consume(); return; } // 5. ESC：撤销 if (keyCode == KeyEvent.VK_ESCAPE) { undoLastAction(); e.consume(); return; } } }

关键细节：

• e.consume()必须调用，否则方向键会触发JTextField默认的文本选择行为，导致焦点混乱。
• VK_NUMPAD1等数字小键盘键未处理，因课程设计作业中用户习惯主键盘，且小键盘键码需额外判断，增加复杂度却不提升核心体验。

4.2 实现方向键焦点移动：计算行列索引并请求焦点

private void moveFocus(JTextField current, int keyCode) { // 从 JTextField 反推其在 9×9 中的行列（需提前存储） int[] pos = getCellPosition(current); int row = pos[0], col = pos[1]; switch (keyCode) { case KeyEvent.VK_UP: row = (row - 1 + 9) % 9; break; case KeyEvent.VK_DOWN: row = (row + 1) % 9; break; case KeyEvent.VK_LEFT: col = (col - 1 + 9) % 9; break; case KeyEvent.VK_RIGHT: col = (col + 1) % 9; break; } // 根据新行列找到对应 JTextField 并请求焦点 JTextField target = getCellAt(row, col); if (target != null) { target.requestFocusInWindow(); target.selectAll(); // 选中全部，方便快速覆盖输入 } } // 辅助方法：getCellPosition() 需在 initBoardPanel 时为每个 JTextField 设置 clientProperty // 如：cell.putClientProperty("row", 0); cell.putClientProperty("col", 0);

提示：requestFocusInWindow()是安全的焦点请求方式，比requestFocus()更可靠，尤其在多层嵌套面板中。selectAll()是玄学优化——用户按方向键后，光标自动选中内容，再按数字键即可覆盖，无需先按 Delete。

5. 避坑指南：Swing 数独开发中 5 个高频翻车点与解法

Swing 的事件模型和线程模型是新手最大陷阱。以下问题均来自某实验室学生提交的 37 份作业的共性错误，按出现频率排序，每条含现象、根因、解决路径。

5.1 现象：窗口缩放后，单元格大小不一致，网格严重变形

原因：未为JTextField显式设置preferredSize，且GridLayout间隙（hgap/vgap）设为0，导致pack()计算时，空单元格与含数字单元格渲染高度不同，GridLayout按最大高度拉伸整行。
解决：

• 所有JTextField必须调用setPreferredSize(new Dimension(40,40))；
• GridLayout构造时hgap/vgap至少设1，避免像素级粘连；
• 禁用setResizable(false)，强制用户适应响应式布局。

5.2 现象：按方向键时，焦点乱跳，甚至跳到按钮上

原因：JTextField默认FocusTraversalPolicy是按添加顺序遍历，9×9 网格按宫格顺序添加（0宫→1宫→…），导致物理位置相邻的格子逻辑索引不连续。
解决：

• 重写FocusTraversalPolicy，按行列索引排序：

  setFocusTraversalPolicy(new LayoutFocusTraversalPolicy() { @Override protected Component getDefaultComponent(Container aContainer) { return getCellAt(0, 0); // 起始点设为左上角 } });

• 或更简单：在moveFocus()中，用getCellAt(row,col)精确获取目标组件，不依赖 Swing 默认遍历。

5.3 现象：输入数字后，规则校验不触发，或校验结果延迟一帧

原因：KeyListener的keyReleased事件中读取getText()，此时Document的insertString()可能尚未完成，读到的是旧值；或校验逻辑放在keyPressed，但Document修改在之后。
解决：

• 永远不在KeyListener中读取getText()做业务逻辑；
• 校验必须在Document的insertString()成功后回调（见 3.2 节），确保数据已落库；
• 若需 UI 反馈（如标红错误格），用SwingUtilities.invokeLater()确保在 EDT 中更新。

5.4 现象：生成的“随机数独”有多个解，或根本无解

原因：简单随机填数 + 删除策略（如随机删20格）无法保证唯一解。课程设计中常误用Math.random()直接填数，忽略数独求解器验证。
解决：

• 采用“先生成完整解，再挖洞”策略：
  1. 用回溯法生成一个有效终局（耗时<100ms）；
  2. 按对称位置成对删除数字（如删 (0,0) 必删 (8,8)），每次删后用求解器验证是否仍唯一解；
  3. 删除至目标空格数（如40格）即停。
• 求解器可用简易回溯（课程设计够用），勿强求 Dancing Links。

5.5 现象：点击“新游戏”按钮后，界面卡死几秒，期间无法操作

原因：newGame()方法中，生成新数独、清空所有格子、重置状态等操作全在 EDT 中执行，阻塞了事件队列。
解决：

• 将耗时操作（生成数独）移至SwingWorker：

  SwingWorker<SudokuBoard, Void> worker = new SwingWorker<>() { @Override protected SudokuBoard doInBackground() throws Exception { return generateNewPuzzle(); // 耗时操作 } @Override protected void done() { try { SudokuBoard board = get(); updateUIWithBoard(board); // 在 EDT 中更新界面 } catch (Exception ex) { showError(ex); } } }; worker.execute();

• updateUIWithBoard()中，批量更新JTextField文本，避免逐个setText()触发多次重绘。

6. 进阶技巧：用 UndoManager 实现原子化撤销与性能优化

课程设计作业常把“撤销”做成简单栈存字符串，导致内存爆炸（每步存 81 字符 × 100 步 = 8KB）。更优解是UndoManager+UndoableEdit，它只存差异，且天然支持canUndo()/canRedo()状态联动。

6.1 定义 CellEdit：描述单格修改的原子操作

class CellEdit implements UndoableEdit { private final JTextField cell; private final char oldValue; private final char newValue; private final int row, col; public CellEdit(JTextField cell, char oldValue, char newValue, int row, int col) { this.cell = cell; this.oldValue = oldValue; this.newValue = newValue; this.row = row; this.col = col; } @Override public void undo() throws CannotUndoException { cell.setText(oldValue == ' ' ? "" : String.valueOf(oldValue)); // 同步更新内部数独数据模型 sudokuModel.setCell(row, col, oldValue); } @Override public void redo() throws CannotRedoException { cell.setText(newValue == ' ' ? "" : String.valueOf(newValue)); sudokuModel.setCell(row, col, newValue); } @Override public boolean canUndo() { return true; } @Override public boolean canRedo() { return true; } @Override public String getPresentationName() { return "修改格子 (" + row + "," + col + ")"; } }

6.2 集成 UndoManager 并绑定到动作

private UndoManager undoManager = new UndoManager(); // 在 fillCell() 方法中，每次合法修改后： public void fillCell(JTextField cell, char digit) { char old = getCellValue(cell); // 从模型读旧值 // ... 执行 setText 等 UI 更新 sudokuModel.setCell(row, col, digit); // 发布原子编辑 CellEdit edit = new CellEdit(cell, old, digit, row, col); undoManager.addEdit(edit); // 更新菜单/按钮状态 updateUndoRedoActions(); } private void updateUndoRedoActions() { undoAction.setEnabled(undoManager.canUndo()); redoAction.setEnabled(undoManager.canRedo()); }

性能对比（实测某模拟项目X）：

我的习惯是：课程设计作业里，只要涉及“撤销”需求，第一反应就是UndoManager。它不是炫技，而是 Swing 对“可逆操作”最原生的支持——不用自己维护栈、不用手动同步状态、不用操心线程安全（UndoManager内部已处理）。当年在某公司做内部工具时，也是靠这套机制把一个 500 行的配置编辑器撤销功能从 3 天砍到 2 小时。希望帮到你。

本文还有配套的精品资源，点击获取