跳到主要内容

点击穿透与 swallow

swallow 用来控制鼠标点到某个 GUI 组件时，这次点击是否继续传递给更底层的组件。

它主要用于处理“上层展示组件挡住下层按钮或槽位”的问题。比如你在按钮上方放了一张背景图、一段文字、一个物品预览或实体预览，如果这个展示组件吞掉了点击，玩家点到它时底层按钮就不会响应。

什么时候使用​

保持默认穿透：

  • 背景图、装饰图、说明文字。
  • 只负责展示的物品、实体、颜色块。
  • 放在按钮或槽位上方，但不希望影响点击的组件。

开启吞掉点击：

  • 弹窗遮罩，防止玩家点到底层界面。
  • 锁定区域，临时禁止操作某一块 GUI。
  • 需要组件本身接管鼠标区域的复杂交互。

支持的组件​

以下展示型组件支持 swallow：

  • texture
  • color
  • gif
  • frame
  • video
  • label
  • entity
  • item

这些组件默认 swallow: false，也就是点击会继续穿透到下面的组件。

基础写法​

background:
  type: texture
  path: textures/gui/background.png
  locationX: 0
  locationY: 0
  width: w
  height: h
  swallow: false

上面的背景图不会拦截鼠标，玩家仍然可以点到背景图下面的按钮或槽位。

弹窗遮罩​

dialogMask:
  type: texture
  path: textures/gui/mask.png
  locationX: 0
  locationY: 0
  width: w
  height: h
  locationZ: 100
  swallow: true

当 dialogMask 位于按钮、槽位等组件上方时，玩家点到遮罩区域，点击会被遮罩吞掉，不会继续传给底层组件。

拖动区域​

options.dragSwallow 和组件的 swallow 不是同一个配置。

options:
  dragSwallow: true
  drag:
    locationX: 0
    locationY: 0
    width: 180
    height: 28

dragSwallow 只控制窗口拖动区域。开启后，玩家按住拖动条拖动窗口时，不会同时点到其他组件。

如果拖动条本身也是一张图片，例如：

titleBar:
  type: texture
  path: textures/gui/title_bar.png
  locationX: 0
  locationY: 0
  width: 180
  height: 28
  swallow: false

图片组件自己的 swallow 仍然按组件规则生效，拖动区域是否吞点击由 options.dragSwallow 决定。

服务端 API​

使用服务端 API 动态创建 GUI 时，可以通过组件的 setSwallow(boolean) 设置：

new GermGuiTexture("mask")
    .setPath("textures/gui/mask.png")
    .setLocationX("0")
    .setLocationY("0")
    .setWidth("w")
    .setHeight("h")
    .setSwallow(true);

服务端会把该字段同步给客户端，客户端根据组件区域判断是否继续传递本次点击。