JavaFX中sizeToScene()不遵循Stage最大值的问题排查

问题 #

在设置了最大值的透明窗口上调用sizeToScene()时出现异常行为：

• 测试场景：将StackPane的prefWidth设为大于Stage的maxWidth值，Stage首次显示时，StackPane会自动适配Stage的maxWidth调整宽度，符合预期；
• 异常现象：之后调用sizeToScene()后，内容会按照prefSize渲染，不再遵循Stage的最大值限制。

测试代码如下：

import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.layout.HBox;
import javafx.scene.layout.StackPane;
import javafx.stage.Stage;
import javafx.stage.StageStyle;

public class SizeToSceneOnTransparentWindow_Demo extends Application {

    Stage stage;

    @Override
    public void start(Stage primaryStage) throws Exception {
        Button show = new Button("Show");
        show.setOnAction(e -> {
            if(stage==null) {
                stage = new Stage();
                stage.initStyle(StageStyle.TRANSPARENT);
                stage.setMaxWidth(200);

                Label label = new Label("Test");
                StackPane container = new StackPane(label);
                container.setStyle("-fx-background-color:#FF000050;-fx-border-width:2px;-fx-border-color:#888888;");
                container.setPrefSize(300, 300);

                label.setOnMouseClicked(e1 -> {
                    stage.sizeToScene();
                });

                StackPane root = new StackPane(container);
                stage.setScene(new Scene(root));
                stage.setX(200);
                stage.setY(200);
            }
            stage.show();
        });
        Button hide = new Button("Hide");
        hide.setOnAction(e -> stage.hide());

        Scene scene = new Scene(new HBox(10,show, hide), 200,200);
        primaryStage.setScene(scene);
        primaryStage.show();
    }
}

疑问：这是JavaFX的bug还是预期行为？sizeToScene()定义在Window类中，而最大值设置在Stage类中，看起来sizeToScene()可能不会考虑Stage的最大值。另外，sizeToScene()的文档说明是将窗口宽高调整为匹配场景内容的大小，仅在窗口不允许调整（如最大化、全屏）时会忽略请求，但实际现象却是场景或内容被调整，与文档描述不符。

分析与结论 #

这属于JavaFX的预期行为，核心原因如下：

1. sizeToScene()的设计逻辑是让窗口尺寸匹配场景的首选大小，不会主动关联Stage的maxWidth/maxHeight属性。首次显示时Stage的max限制生效是因为布局系统的初始约束，但调用sizeToScene()时，方法会直接根据场景内容的prefSize重新计算窗口尺寸，此时不会再触发max属性的约束逻辑。
2. 文档中“仅在窗口不允许调整时忽略请求”的描述，这里的“不允许调整”特指窗口处于最大化、全屏等锁定状态，而非Stage设置的max属性，这部分文档表述确实存在模糊性，容易引发误解。
3. 该现象并非透明窗口独有，普通窗口调用sizeToScene()时也会出现相同的max属性失效问题。

如果需要让sizeToScene()遵循Stage的max限制，可以手动添加约束逻辑：

label.setOnMouseClicked(e1 -> {
    stage.sizeToScene();
    // 手动应用maxWidth/maxHeight限制
    stage.setWidth(Math.min(stage.getWidth(), stage.getMaxWidth()));
    stage.setHeight(Math.min(stage.getHeight(), stage.getMaxHeight()));
});

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