FXML是JavaFX的XML界面描述文件，用于分离UI结构与逻辑代码；根节点为布局容器，控件映射为XML元素，通过fx:id注入字段、fx:controller指定控制器、onAction绑定事件，需用FXMLLoader加载并确保路径、ID、方法签名正确。
FXML 是 JavaFX 的 XML 格式界面描述文件，它把 UI 结构和逻辑代码分离，类似 HTML 之于 JavaScript —— 你不用在 Java 里硬写一堆 Button、VBox 实例化语句，而是用声明式语法定义组件树。
FXML 文件怎么写？关键标签和属性有哪些
一个合法的 FXML 文件本质是 XML，根节点通常是 AnchorPane、BorderPane 或 VBox 等布局容器。每个控件对应一个 XML 元素，属性直接映射到 JavaFX 类的 setter 方法（如 text → setText()），fx:id 用于在 Java 代码中注入对应字段。
-
fx:controller属性必须指定控制器类全限定名，且该类需有无参构造器 -
fx:id值必须与控制器中同名@FXML字段类型匹配（比如<button fx:id="saveBtn"></button>要求控制器里有@FXML private Button saveBtn;） - 事件处理用
onAction="#handleSave"，对应控制器中public void handleSave(ActionEvent e) - 不要手动写
xmlns命名空间 —— Scene Builder 自动生成的才可靠；手写时至少保留xmlns:fx="http://javafx.com/fxml/1"
<?xml version="1.0" encoding="UTF-8"?>
<VBox xmlns="http://javafx.com/javafx/19" xmlns:fx="http://javafx.com/fxml/1" fx:controller="app.MainController">
<children>
<Label text="Hello FXML"/>
<Button text="Click me" onAction="#onButtonClick" fx:id="clickBtn"/>
</children>
</VBox>
如何加载 FXML 并显示窗口
核心是 FXMLLoader：它解析 XML、实例化对象、注入 @FXML 字段、绑定事件，并返回根节点。不能直接 new 控制器——必须让 FXMLLoader 创建它，否则 @FXML 字段为 null。
- 调用
loader.load()前，确保loader.setLocation()指向正确路径（推荐用getClass().getResource("main.fxml")） - 如果控制器类不在默认包，
fx:controller必须写全名（如app.MainController），且类在 classpath 中可访问 - 加载后得到的是根节点（如
VBox），需把它设为Scene内容，再塞进Stage - 别在控制器构造器里访问
@FXML字段——此时尚未注入；应改用initialize()方法（需声明为public void initialize()，无参数）
FXMLLoader loader = new FXMLLoader();
loader.setLocation(getClass().getResource("main.fxml"));
Parent root = loader.load(); // 此时 MainController 已被创建并注入字段
Scene scene = new Scene(root);
stage.setScene(scene);
stage.show();
常见报错和排查方向
FXML 加载失败几乎都卡在三类问题：路径不对、ID 不匹配、控制器方法签名错误。错误信息里通常带关键词，照着查就行。
立即学习“Java免费学习笔记（深入）”；
-
java.lang.NullPointerException在访问@FXML字段时抛出 → 检查fx:id和字段名是否完全一致（含大小写）、字段是否漏加@FXML、是否用了new MainController()而非让 loader 创建 -
javafx.fxml.LoadException: ... not a valid type→ FXML 中写了不存在的类名（如拼错Button为Buton），或未引入对应命名空间 -
javafx.fxml.LoadException: ... Controller method not found→onAction="#xxx"指向的方法在控制器中不存在，或参数类型不对（必须是ActionEvent或其子类，不能是MouseEvent） - 中文乱码 → 确保 FXML 文件保存为 UTF-8 编码，且 XML 声明中写
encoding="UTF-8"
真正麻烦的不是写 FXML，而是当界面嵌套深、动态加载多层时，fx:id 命名容易冲突，initialize() 的执行时机又依赖加载顺序。这时候别硬扛，优先用 Scene Builder 可视化拖拽生成结构，再手工微调逻辑绑定——人脑不适合维护上百行的手写 XML 布局树。
