矩形组件

矩形组件用于绘制纯色或半透明区域，是制作面板、遮罩、边框底色、进度条和布局辅助背景的基础组件。它不依赖客户端图片素材。

适用场景

界面面板和半透明背景
HUD 底条、进度条底色与填充
选中高亮、区域提示和调试边界
不需要图片素材的轻量装饰

通用配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`id`	ID	字符串	自动生成 `rect_N`	页面内唯一 ID	用于脚本、父级绑定和状态更新。
`type`	类型	只读字符串	`rect`	固定值	创建后不能修改。
`parent`	父级	字符串	空	布局组件 ID	为空表示根级元素。
`z`	层级	整数	`0`	任意整数	背景通常使用较低层级。
`visible`	显示	布尔值	`true`	`true`、`false`	静态显隐开关。
`enabled`	启用	布尔值	`true`	`true`、`false`	不需要事件时可设为 `false`。
`pointerEvents`	指针处理	枚举	`auto`	`auto`、`block`、`pass`	背景通常用 `pass`；弹窗遮罩用 `block` 防止点击穿透。
`scale`	缩放	数字或公式	`1`	非负值	以矩形中心缩放画面和命中范围，不改变布局值。
`opacity`	透明度	数字或公式	`1`	`0` 至 `1`	控制矩形透明度，不改变命中。
`visibleWhen`	显示条件	条件表达式	空	只读条件	可根据变量控制显示。
`enabledWhen`	启用条件	条件表达式	空	只读条件	可根据变量控制交互。
`tooltip`	多行提示	字符串列表	空	最多 32 行，每行最多 256 字符	鼠标悬浮提示。
`containerBinding`	容器绑定	字符串	空	当前容器的语义槽位 ID	仅容器替换页面使用，可读取绑定物品信息。
`containerTooltip`	容器提示	布尔值	`true`	`true`、`false`	没有显式 `tooltip` 时是否显示绑定物品提示。
`layout.x`	X	数字或公式	创建时画布位置	合法布局公式	矩形左上角 X。
`layout.y`	Y	数字或公式	创建时画布位置	合法布局公式	矩形左上角 Y。
`layout.width`	宽	数字或公式	`80`	合法布局公式	矩形宽度。
`layout.height`	高	数字或公式	`24`	合法布局公式	矩形高度。
`events.leftPress` `/rightPress/middlePress`	按下脚本	ChaUI Script	空	多行脚本	对应按键按下时触发。
`events.leftRelease` `/rightRelease/middleRelease`	松开脚本	ChaUI Script	空	多行脚本	对应按键捕获仍有效并松开时触发。
`events.leftClick`	左键脚本	ChaUI Script	空	多行脚本	左键点击时触发。
`events.rightClick`	右键脚本	ChaUI Script	空	多行脚本	右键点击时触发。
`events.middleClick`	中键脚本	ChaUI Script	空	多行脚本	中键点击时触发。
`events.hoverEnter`	悬浮进入脚本	ChaUI Script	空	多行脚本	鼠标进入时触发。
`events.hoverLeave`	悬浮离开脚本	ChaUI Script	空	多行脚本	鼠标离开时触发。

专属配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`rect.color`	颜色	六位十六进制颜色	`#5A636B`	`#RRGGBB`	只控制红、绿、蓝；透明度使用组件根级 `opacity`。

颜色固定填写 # 加六位十六进制数字，例如 #202730 是深灰蓝，#FFAA00 是橙色。半透明背景直接在组件根级填写 opacity: 0.75，不需要进行颜色换算。

配置示例

yaml

- id: panel_background
  type: rect
  parent: ""
  visible: true
  enabled: false
  pointerEvents: pass       # 纯背景不接收鼠标
  scale: 1
  opacity: 0.88             # 略微透明
  z: 0
  layout:
    x: window.width * 0.5 - 110
    y: window.height * 0.5 - 65
    width: 220
    height: 130
  rect:
    color: "#202730"        # 固定六位 RRGGBB
  tooltip: []
  events: {}

矩形即使不允许点击，也可以在创建事件中读取自己的尺寸和颜色：

yaml

events:
  create: |-
    vars.panelWidth = component("panel_background").layout.width
    vars.panelColor = component("panel_background").rect.color

常见问题

矩形挡住了文字或按钮

纯背景建议设置 pointerEvents: pass。需要制作弹窗遮罩时改用 pointerEvents: block，这样遮罩会主动挡住后方按钮；同时通过 z 确保弹窗按钮位于遮罩上方。

颜色完全看不到

检查颜色是否为完整六位 #RRGGBB，并确认组件根级 opacity 大于 0。例如深色背景可以写 color: "#202730" 和 opacity: 0.8。

能否使用渐变或九宫格图片

纯矩形只绘制单一颜色。复杂背景可使用图片组件和源图选区；后续扩展能力不会改变当前矩形字段。

创建事件

矩形支持 events.create，可在页面打开后根据变量设置初始显隐、尺寸或布局。初始矩形与脚本新增、复制的矩形实例分别触发一次；编辑模式不执行，预览在隔离副本中执行。

服务端配置文件 ↘

矩形组件 ​

适用场景 ​

通用配置 ​

专属配置 ​

配置示例 ​

常见问题 ​

矩形挡住了文字或按钮 ​

颜色完全看不到 ​

能否使用渐变或九宫格图片 ​

创建事件 ​