JavaFX FXML onAction绑定触发LoadException，求助问题排查

问题场景 #

运行JavaFX程序时抛出如下错误：

javafx.fxml.LoadException: Error resolving onAction='#changeUser', either the event handler is not in the Namespace or there is an error in the script.

移除FXML中按钮的onAction属性后，程序可正常启动并显示包含三个按钮的窗口。已排查多项常见问题但未找到根源。

相关代码 #

控制器类 CTRLUsermenu.java #

package user;

import java.net.URL;
import java.util.ResourceBundle;

import javafx.event.ActionEvent;
import javafx.fxml.FXML;
import javafx.fxml.Initializable;
import javafx.scene.control.Button;

public class CTRLUsermenu implements Initializable{
    @FXML
    private Button  change_user;
    @FXML
    private Button  admin_users;

    @FXML
    private static void changeUser(ActionEvent e) {
        // System.out.println("test");
    }

    @FXML
    private static void adminUsers() {
        // System.out.println("test");
    }

    @Override
    public void initialize(URL location, ResourceBundle resources) {
    }
}

FXML文件 usermenu.fxml #

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.Button?>
<?import javafx.scene.layout.VBox?>

<VBox alignment="CENTER" spacing="20.0" fx:controller="user.CTRLUsermenu" xmlns="http://javafx.com/javafx/17" xmlns:fx="http://javafx.com/fxml/1">
   <children>
      <Button fx:id="change_user" mnemonicParsing="false" prefWidth="160" text="Change User" onAction="#changeUser"/>
      <Button fx:id="admin_users" mnemonicParsing="false" prefWidth="160" text="User administration" onAction="#adminUsers"/>
      <Button cancelButton="true" mnemonicParsing="false" prefWidth="160" text="Cancel" />
   </children>
</VBox>

已排除的常见问题 #

• FXML注解使用错误
• 导入AWT类引发冲突
• 控制器未实现Initializable接口
• 文件名、类名、方法名拼写错误
• 方法参数类型不匹配

问题根源与解决办法 #

根源 #

JavaFX的FXML事件处理器方法不支持静态方法。FXML加载器会从控制器的实例对象中查找对应的事件处理方法，而静态方法属于类而非实例成员，无法被正确绑定，因此触发LoadException。

解决办法 #

移除控制器中changeUser和adminUsers方法的static修饰符，改为实例方法：

@FXML
private void changeUser(ActionEvent e) {
    // System.out.println("test");
}

@FXML
private void adminUsers() {
    // System.out.println("test");
}

修改完成后重新运行程序，事件处理器即可正常绑定，错误消失。

内容的提问来源于stack exchange，提问作者thebert