JavaFX实现Node部分鼠标透明：兼顾自身事件接收与下层事件穿透

场景说明 #

在StackPane布局的开发过程中，常需要实现顶层节点的部分鼠标透明能力：既要保证顶层节点可正常响应自身的鼠标检测类事件，又要让重叠区域的交互类鼠标事件正常传递给下层节点响应。
典型布局结构为StackPane内放置两个矩形Pane，下层Pane尺寸更小、完全处于上层Pane的覆盖范围下：

<StackPane>
    <Pane onMouseEntered="#printA" onMouseClicked="#printB" />
    <Pane onMouseEntered="#printC" />
</StackPane>

对应交互预期：

• 鼠标移动到上层Pane任意区域时，控制台输出C
• 鼠标移动到上下层重叠的下层Pane区域时，控制台同时输出A
• 鼠标在重叠的下层Pane区域点击时，控制台输出B
• 鼠标在上层Pane的非重叠区域点击时，不触发任何响应
  这类需求的典型业务场景为：在Pane中心内容区外设置更大范围的鼠标检测区，鼠标进入检测区时自动将中心内容从展示模式切换为可编辑模式；由于检测范围大于中心内容区，会与Pane内其他元素重叠，需要使用叠放在上层的透明节点承担检测职责，且节点需持续存在以感知鼠标移出检测区的时机。

现有社区方案的适配缺陷 #

• 对上层节点设置setMouseTransparent(true)：会导致上层节点完全无法接收鼠标事件，无法触发自身的进入监听逻辑
• 对上层节点设置setPickOnBounds(true)：视觉透明区域的鼠标事件会直接穿透，这类区域上层节点无法接收自身事件；不透明区域则会完全阻断下层节点的事件触发，无论上层节点是全透明还是全不透明配置，都无法满足需求
• 将上层节点的visible属性设置为false：会导致节点直接从渲染树移除，无法接收自身鼠标事件，无法适配持续感知鼠标移出的要求

可落地的实现方案 #

利用JavaFX的事件分发与手动触发机制，在上层节点的事件过滤器中做事件分流处理，核心逻辑为：

• 在上层节点需要持续感知的检测类事件（如MouseEntered、MouseExited），不做拦截，由上层节点正常接收处理，保证鼠标检测逻辑正常运行
• 在上层节点不需要响应的交互类事件（如MouseClicked、MousePressed、MouseReleased），先判断当前鼠标坐标是否落在下层节点的实际bounds范围内：
  • 若落在重叠区域内，将当前事件拷贝后手动触发给下层节点处理，同时消费掉事件，避免上层节点的默认响应逻辑误触发
  • 若落在非重叠区域，直接消费掉事件，不做额外转发，保证非重叠区域的交互不会触发其他节点响应
    对应Java代码示例：

// 初始化两个Pane与根布局
Pane lowerPane = new Pane();
Pane upperPane = new Pane();
StackPane root = new StackPane(lowerPane, upperPane);

// 为上层Pane绑定事件过滤器实现分流
upperPane.addEventFilter(MouseEvent.ANY, event -> {
    // 放行上层需要的检测类事件
    EventType<? extends MouseEvent> targetType = event.getEventType();
    if (targetType == MouseEvent.MOUSE_ENTERED || targetType == MouseEvent.MOUSE_EXITED) {
        return;
    }

    // 转换坐标，判断当前鼠标位置是否在下层Pane范围内
    Bounds lowerBoundsInUpper = upperPane.sceneToLocal(lowerPane.getBoundsInScene());
    Point2D mouseLocalPos = new Point2D(event.getX(), event.getY());
    if (lowerBoundsInUpper.contains(mouseLocalPos)) {
        // 将事件转发给下层Pane处理
        MouseEvent copiedEvent = event.copyFor(lowerPane, lowerPane);
        lowerPane.fireEvent(copiedEvent);
        // 消费事件，阻断后续上层节点的事件处理
        event.consume();
    }
});

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