JavaFX 8升级18后TreeView布局异常isNeedsLayout未复位问题

现象本质 #

观测到的脉冲结束后部分节点isNeedsLayout仍为true、首次选中节点文本偏移的问题，是JavaFX 9之后VirtualFlow组件性能优化带来的实现变更与已知回归，并非业务代码写法错误：

• JavaFX 8中布局逻辑为单脉冲同步执行：所有标记为需要布局的节点会在当前脉冲周期内完成布局计算，执行完成后立即将所有相关节点的isNeedsLayout标记重置为false，和早期版本的开发认知一致。
• JavaFX 9至18版本对VirtualFlow（TreeView、TableView等虚拟化列表控件的核心滚动容器）做了增量布局优化：可见区域内单元格的布局计算被延迟到下一个脉冲的视口校准阶段执行，isNeedsLayout标记的清理时机和布局执行时机被解耦，因此脉冲结束时观测到的true值不代表节点未完成布局，只是脏标记未被同步清理。
• 首次选中时的文本偏移是该优化引入的已知布局bug：自定义CSS修改了展开、选中状态下tree-disclosure节点的padding值，状态变更时单元格的布局请求没有在当前脉冲同步触发，Graphic节点（自定义Label）使用了旧的位置参数渲染，下一个脉冲才会修正位置，因此出现肉眼可见的偏移。

修复方案 #

按优先级从高到低选择即可：

• 升级JavaFX版本到19及以上
  该布局偏移问题在JavaFX 19版本中已正式修复，对应OpenJFX工单为JDK-8279226。修复后VirtualFlow会在选中、展开折叠等状态变更时，强制触发当前可见区域所有单元格的同步布局计算，isNeedsLayout标记的清理逻辑也和布局执行重新对齐，不会再出现脉冲结束后脏标记残留、文本偏移的问题。
• 无法升级版本时，手动补发布局请求
  在自定义TreeCell中监听选中、展开状态变化，状态变更时手动调用requestLayout()强制当前单元格同步重新布局，修改CellFactory代码如下：

fxTree.setCellFactory(t -> new TreeCell<String>() {
    Label lbl = new Label();

    // 构造方法中添加状态监听
    {
        selectedProperty().addListener((ob, oldVal, newVal) -> requestLayout());
        expandedProperty().addListener((ob, oldVal, newVal) -> requestLayout());
    }

    @Override
    protected void updateItem(String item, boolean empty) {
        super.updateItem(item, empty);
        setText(null);
        if (item != null) {
            lbl.setText(item);
            setGraphic(lbl);
        } else {
            setGraphic(null);
        }
    }

    @Override
    protected void layoutChildren() {
        super.layoutChildren();
        if (getItem() != null) {
            System.out.println("Layouting ::> " + getItem());
        }
    }
});

• 调整CSS写法避免触发不必要的布局请求
  原有CSS在不同状态下修改disclosure节点的padding，会强制单元格重新计算尺寸触发布局。可以将padding改为固定值，用transform属性调整箭头位置，transform属于渲染层变换不会触发布局重算，从根源上避免状态变更时的布局抖动：

.virtual-flow .clipped-container .sheet .tree-cell .tree-disclosure-node > .arrow {
  -fx-background-color: #77797a;
}

.virtual-flow .clipped-container .sheet .tree-cell .tree-disclosure-node {
  -fx-padding: 4px 6px 4px 8px; /* 固定为默认padding，不随状态修改 */
}

.virtual-flow .clipped-container .sheet .tree-cell:expanded > .tree-disclosure-node > .arrow {
  -fx-translate-y: 2px; /* 用位移替代padding调整箭头位置，不触发布局 */
}

.virtual-flow .clipped-container .sheet .tree-cell:selected > .tree-disclosure-node > .arrow {
  -fx-background-color: #f7f7f7;
}

开发注意事项 #

JavaFX 9之后不要依赖isNeedsLayout() == false作为节点布局完成的判断标准，该标记仅代表「节点存在待处理的布局请求」，不代表「当前节点布局未完成」。如果需要在节点布局完成后执行逻辑，正确的做法是监听节点的layoutBounds属性变化，或者重写节点的layoutChildren()方法插入自定义逻辑，不要通过轮询脏标记判断布局状态。

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