JavaFX自定义组件在SceneBuilder中注入失败及类型识别异常

我使用Java 20、JavaFX 20和Maven开发小型个人项目，在创建可复用组件并通过主场景控制器操作时遇到问题：按官方文档步骤创建自定义组件后，在SceneBuilder中导入其FXML文件并添加到主场景，为组件设置fx:id后在控制器类中声明对应Custom类型字段，却出现类型不匹配错误：无法将javafx.scene.layout.VBox赋值给app.components.Custom类型的字段。奇怪的是，SceneBuilder的层级面板中组件名为Custom，但显示类型为VBox，导致SceneBuilder提示找不到可注入字段。

错误信息 #

Exception in Application start method
java.lang.reflect.InvocationTargetException
    at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:119)
    at java.base/java.lang.reflect.Method.invoke(Method.java:578)
    at javafx.graphics@20/com.sun.javafx.application.LauncherImpl.launchApplicationWithArgs(LauncherImpl.java:464)
    at javafx.graphics@20/com.sun.javafx.application.LauncherImpl.launchApplication(LauncherImpl.java:363)
    at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:104)
    at java.base/java.lang.reflect.Method.invoke(Method.java:578)
    at java.base/sun.launcher.LauncherHelper$FXHelper.main(LauncherHelper.java:1081)
Caused by: java.lang.RuntimeException: Exception in Application start method
    at javafx.graphics@20/com.sun.javafx.application.LauncherImpl.launchApplication1(LauncherImpl.java:893)
    at javafx.graphics@20/com.sun.javafx.application.LauncherImpl.lambda$launchApplication$2(LauncherImpl.java:195)
    at java.base/java.lang.Thread.run(Thread.java:1623)
Caused by: javafx.fxml.LoadException: 
/C:/Users/user/Desktop/eclipse-workspace/Project 3/target/classes/app/views/fxml/Menu.fxml:43

    at javafx.fxml@20/javafx.fxml.FXMLLoader.constructLoadException(FXMLLoader.java:2722)
    at javafx.fxml@20/javafx.fxml.FXMLLoader.loadImpl(FXMLLoader.java:2700)
    at javafx.fxml@20/javafx.fxml.FXMLLoader.loadImpl(FXMLLoader.java:2563)
    at javafx.fxml@20/javafx.fxml.FXMLLoader.load(FXMLLoader.java:2531)
    at app/app.Main.loadFXML(Main.java:29)
    at app/app.Main.start(Main.java:17)
    at javafx.graphics@20/com.sun.javafx.application.LauncherImpl.lambda$launchApplication1$9(LauncherImpl.java:839)
    at javafx.graphics@20/com.sun.javafx.application.PlatformImpl.lambda$runAndWait$12(PlatformImpl.java:483)
    at javafx.graphics@20/com.sun.javafx.application.PlatformImpl.lambda$runLater$10(PlatformImpl.java:456)
    at java.base/java.security.AccessController.doPrivileged(AccessController.java:400)
    at javafx.graphics@20/com.sun.javafx.application.PlatformImpl.lambda$runLater$11(PlatformImpl.java:455)
    at javafx.graphics@20/com.sun.glass.ui.InvokeLaterDispatcher$Future.run(InvokeLaterDispatcher.java:95)
    at javafx.graphics@20/com.sun.glass.ui.win.WinApplication._runLoop(Native Method)
    at javafx.graphics@20/com.sun.glass.ui.win.WinApplication.lambda$runLoop$3(WinApplication.java:185)
    ... 1 more
Caused by: java.lang.IllegalArgumentException: Can not set app.components.Custom field app.controllers.Menu.cc to javafx.scene.layout.VBox
    at java.base/jdk.internal.reflect.FieldAccessorImpl.throwSetIllegalArgumentException(FieldAccessorImpl.java:228)
    at java.base/jdk.internal.reflect.FieldAccessorImpl.throwSetIllegalArgumentException(FieldAccessorImpl.java:232)
    at java.base/jdk.internal.reflect.MethodHandleObjectFieldAccessorImpl.set(MethodHandleObjectFieldAccessorImpl.java:115)
    at java.base/java.lang.reflect.Field.set(Field.java:834)
    at javafx.fxml@20/javafx.fxml.FXMLLoader.injectFields(FXMLLoader.java:1175)
    at javafx.fxml@20/javafx.fxml.FXMLLoader$ValueElement.processValue(FXMLLoader.java:870)
    at javafx.fxml@20/javafx.fxml.FXMLLoader$ValueElement.processStartElement(FXMLLoader.java:764)
    at javafx.fxml@20/javafx.fxml.FXMLLoader.processStartElement(FXMLLoader.java:2853)
    at javafx.fxml@20/javafx.fxml.FXMLLoader.loadImpl(FXMLLoader.java:2649)
    ... 13 more
Exception running application app.Main

相关代码文件 #

Custom.java #

package app.components;

import java.io.IOException;

import app.Main;
import javafx.fxml.FXML;
import javafx.fxml.FXMLLoader;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.layout.VBox;

public class Custom extends VBox {
    
    @FXML private Button plusBtn;
    @FXML private Button minusBtn;
    @FXML private Label label;
    
    public Custom() {
        FXMLLoader loader = new FXMLLoader(Main.class.getResource("components/Custom.fxml"));
        loader.setRoot(this);
        loader.setController(this);
        try {
            loader.load();
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }
    
    public void newText(String text) {
        label.setText(text);
    }
}

Custom.fxml #

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

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

<VBox alignment="CENTER" maxHeight="-Infinity" maxWidth="-Infinity" minHeight="-Infinity" minWidth="-Infinity" xmlns="http://javafx.com/javafx/19" xmlns:fx="http://javafx.com/fxml/1">
   <children>
      <Button fx:id="plusBtn" mnemonicParsing="false" text="+" />
      <Label fx:id="label" text="Label" />
      <Button fx:id="minusBtn" mnemonicParsing="false" text="-" />
   </children>
</VBox>

Menu.java #

package app.controllers;

import app.components.Custom;

public class Menu {

    @FXML
    private Custom cc;

    public void initialize() {
        cc.newText("Test");
    }
}

module-info.java #

module app {
    requires javafx.controls;
    requires javafx.fxml;
    requires javafx.media;
    requires javafx.graphics;
    requires javafx.base;
    
    opens app to javafx.fxml;
    opens app.controllers to javafx.fxml;
    
    exports app;
}

问题原因 #

直接将Custom.fxml作为普通VBox导入主FXML时，FXMLLoader加载主FXML只会创建VBox实例，而非你的Custom子类实例。SceneBuilder显示的类型也印证了这一点——它识别的是FXML根节点的VBox类型，而非自定义的Custom类。

解决步骤 #

1. 修改Custom.fxml的根节点 #

将FXML根节点改为<fx:root>，指定类型为VBox，并确保命名空间版本与JavaFX 20一致：

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

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

<fx:root type="javafx.scene.layout.VBox" alignment="CENTER" maxHeight="-Infinity" maxWidth="-Infinity" minHeight="-Infinity" minWidth="-Infinity" xmlns="http://javafx.com/javafx/20" xmlns:fx="http://javafx.com/fxml/1">
   <children>
      <Button fx:id="plusBtn" mnemonicParsing="false" text="+" />
      <Label fx:id="label" text="Label" />
      <Button fx:id="minusBtn" mnemonicParsing="false" text="-" />
   </children>
</fx:root>

2. 主FXML中直接引用Custom类 #

不要导入Custom.fxml，而是在主FXML（Menu.fxml）中使用自定义类的完全限定名作为节点：

<?xml version="1.0" encoding="UTF-8"?>
<?import app.components.Custom?>
<?import javafx.scene.layout.BorderPane?>

<BorderPane xmlns="http://javafx.com/javafx/20" xmlns:fx="http://javafx.com/fxml/1" fx:controller="app.controllers.Menu">
    <center>
        <Custom fx:id="cc" />
    </center>
</BorderPane>

这样FXMLLoader加载主FXML时会创建Custom类的实例，而非VBox。

3. 更新module-info.java #

确保components包对javafx.fxml开放，否则FXMLLoader无法注入FXML字段：

module app {
    requires javafx.controls;
    requires javafx.fxml;
    requires javafx.media;
    requires javafx.graphics;
    requires javafx.base;
    
    opens app to javafx.fxml;
    opens app.controllers to javafx.fxml;
    opens app.components to javafx.fxml; // 新增该行
    
    exports app;
}

4. 验证SceneBuilder识别 #

修改完成后，重新在SceneBuilder中导入项目，主FXML中的Custom组件会被正确识别为app.components.Custom类型，层级面板显示正确类型，fx:id注入也不会再报错。

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