按钮组件

按钮组件是可点击图片，支持普通、悬浮、选中三套素材、GIF、响应式文字、逐字显示，以及左中右三键的按下、松开、点击和悬浮事件。多个按钮可以绑定同一个页面变量，快速做出页签、分类栏和单选按钮。没有可用图片时会显示安全的默认按钮外观。

适用场景

页面确认、关闭和跳转入口
商店购买、任务领取和功能开关
带普通/悬浮状态的图片按钮
页签、分类栏、难度选择等单选按钮组
需要点击、右键或悬浮事件的交互区域

通用配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`id`	ID	字符串	自动生成 `button_N`	页面内唯一 ID	用于脚本和状态更新。
`type`	类型	只读字符串	`button`	固定值	创建后不能修改。
`parent`	父级	字符串	空	布局组件 ID	为空表示根级元素。
`z`	层级	整数	`0`	任意整数	控制按钮绘制顺序。
`visible`	显示	布尔值	`true`	`true`、`false`	静态显隐开关。
`enabled`	启用	布尔值	`true`	`true`、`false`	为假时不响应按钮事件。
`pointerEvents`	指针处理	枚举	`auto`	`auto`、`block`、`pass`	按钮在 `auto` 下天然参与命中；`pass` 会让按钮完全无法交互。
`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.leftPres` `/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	空	多行脚本	鼠标离开时触发一次。

专属配置

文字配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`button.label`	文字	字符串	新建时组件 ID；字段缺失为空	普通文字与 `{表达式}`	绘制在按钮上的文字，可实时读取变量和只读常量。
`button.font`	字体路径	字符串	空	`resourcepacks/ChaUI` 下的安全 `.ttf` 相对路径	使用自定义 TTF；缺失、损坏或不支持的字形安全回退原版字体。
`button.fontResolution`	字体分辨率	整数	`32`	`16` 至 `256`	控制 TTF 字形清晰度，不改变实际文字大小。
`button.color`	文字颜色	颜色	`#FFFFFF`	严格 `#RRGGBB`	按钮文字的基础颜色；透明度继续使用根级 `opacity`。
`button.textSize`	文字大小	正数	`1`	正整数或正小数	按钮文字缩放比例。
`button.textX`	文字X	整数	`6`	任意整数	相对于按钮左上角的文字 X 偏移。
`button.textY`	文字Y	整数	`6`	任意整数	相对于按钮左上角的文字 Y 偏移。
`button.textLineLength`	每行字数	正整数或空	`0`	`0`/空或正整数	按字符数量换行。
`button.textLineWidth`	每行宽度	非负整数或空	`0`	GUI 像素	按应用 `textSize` 后的真实字形宽度换行；`0` 或空表示不限制。
`button.revealIntervalMs`	逐字间隔(ms)	非负整数	`0`	毫秒	`0` 立即显示；正数逐字出现。
`button.align`	对齐	枚举	`left`	`left`、`center`、`right`	在剩余按钮文字区域内对齐。

按钮文字与文本组件使用同一套字体、颜色、响应式文字和换行语义。textLineLength 与 textLineWidth 可以同时设置，任意一项先达到限制就换行；显式换行与空行会保留，单个超宽字形会独占一行。TTF 路径、字形回退和分辨率选择规则可参考文本组件。

text

确认（已选择 {vars.selectedCount} 项）
购买：{vals.papi.price} 金币
生命恢复到 {vals.player.maxHealth}

变量变化后按钮文字会自动刷新。需要完整了解表达式、花括号转义和 PAPI 映射，请阅读响应式变量与实时文字。

普通状态图片

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`button.path`	图片路径	字符串	`gui/button_N.png`	ChaUI 相对图片路径，可含 `{表达式}`	普通状态图片或 GIF；最终路径变化时重新加载。
`button.gifLoop`	GIF循环	布尔值	`true`	`true`、`false`	控制普通状态 GIF 是否循环。
`button.gifLoopCount`	GIF次数	非负整数	`0`	`0` 或正整数	`0` 表示无限循环。
`button.sourceX`	源X	非负整数或公式	空	像素坐标或数字公式	普通素材选区左上角 X。
`button.sourceY`	源Y	非负整数或公式	空	像素坐标或数字公式	普通素材选区左上角 Y。
`button.sourceWidth`	源宽	非负整数或公式	空	像素尺寸或数字公式	普通素材选区宽度；为 `0` 时普通素材不绘制。
`button.sourceHeight`	源高	非负整数或公式	空	像素尺寸或数字公式	普通素材选区高度；为 `0` 时普通素材不绘制。

悬浮状态图片

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`button.hoverPath`	悬浮路径	字符串	`gui/button_N_hover.png`	ChaUI 相对图片路径，可含 `{表达式}`	鼠标悬浮时使用；为空或加载失败时回退普通图片。
`button.hoverGifLoop`	悬浮GIF循环	布尔值	`true`	`true`、`false`	控制悬浮 GIF 是否循环。
`button.hoverGifLoopCount`	悬浮GIF次数	非负整数	`0`	`0` 或正整数	`0` 表示无限循环。
`button.hoverSourceX`	悬浮源X	非负整数或公式	空	像素坐标或数字公式	悬浮素材选区左上角 X。
`button.hoverSourceY`	悬浮源Y	非负整数或公式	空	像素坐标或数字公式	悬浮素材选区左上角 Y。
`button.hoverSourceWidth`	悬浮源宽	非负整数或公式	空	像素尺寸或数字公式	悬浮素材选区宽度；为 `0` 时悬浮素材不绘制。
`button.hoverSourceHeight`	悬浮源高	非负整数或公式	空	像素尺寸或数字公式	悬浮素材选区高度；为 `0` 时悬浮素材不绘制。

选中状态与选中图片

button.checked 用来把按钮绑定到一个页面变量。多个按钮填写同一个变量后，左键点击其中一个按钮，变量会自动变成该按钮的 id，于是同一组里只有对应按钮显示选中图片。

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`button.checked`	选中变量	字符串	空	完整的 `vars.<变量名>`	变量值等于当前按钮 `id` 时进入选中态。
`button.checkedPath`	选中路径	字符串	`gui/button_N_checked.png`	ChaUI 相对图片路径，可含 `{表达式}`	按钮选中时使用的图片或 GIF。
`button.checkedGifLoop`	选中GIF循环	布尔值	`true`	`true`、`false`	控制选中状态 GIF 是否循环。
`button.checkedGifLoopCount`	选中GIF次数	非负整数	`0`	`0` 或正整数	`0` 表示无限循环。
`button.checkedSourceX`	选中源X	非负整数或公式	空	像素坐标或数字公式	选中素材选区左上角 X。
`button.checkedSourceY`	选中源Y	非负整数或公式	空	像素坐标或数字公式	选中素材选区左上角 Y。
`button.checkedSourceWidth`	选中源宽	非负整数或公式	空	像素尺寸或数字公式	选中素材选区宽度；为 `0` 时选中素材不绘制。
`button.checkedSourceHeight`	选中源高	非负整数或公式	空	像素尺寸或数字公式	选中素材选区高度；为 `0` 时选中素材不绘制。

普通、悬浮和选中路径都能使用响应式表达式。例如页面变量 vars.theme 为 dark 时，gui/{vars.theme}/confirm.png 会读取 gui/dark/confirm.png。变量变化后对应素材重新加载，GIF 从第 0 帧开始。最终路径不安全或文件不存在时，按钮只回退到可用状态图片或默认外观，不会影响页面其他组件。

普通、悬浮和选中三组选区也都接受数字公式。每次渲染会使用当前变量重新计算并向下取整；某一状态的结果无效或越界时只让该状态素材不可用，再按按钮状态规则回退。选区与布局宽度配合的完整示例见图片裁剪与动态血条。

选中变量必须填写完整引用，例如 vars.selectedTab，不能只写 selectedTab，也不能写成 vals.selectedTab。根级 vars 可以提前给它一个默认按钮 ID，让页面打开时直接选中某一项；也可以不提前声明，第一次左键点击会在当前页面会话中创建这个变量。

状态优先级固定为：

变量值等于按钮 ID：显示选中图片。
未选中且鼠标悬浮：显示悬浮图片。
其他情况：显示普通图片。

按钮已经选中时，鼠标悬浮不会再切换成悬浮图片。选中图片为空、无法加载或源图选区不可用时，会回退到普通图片，但仍然不会显示悬浮图片，这样选中状态不会因素材问题发生视觉跳变。

在编辑器里制作页签按钮

新建三个按钮，并分别设置容易辨认的 ID，例如 tab_home、tab_shop、tab_task。
三个按钮的“选中变量”都填写 vars.selectedTab。
分别设置普通路径、悬浮路径和选中路径。
在页面默认变量中新增 selectedTab，值填写希望默认打开的按钮 ID，例如 tab_home。
给三个内容区域分别设置显示条件：vars.selectedTab == "tab_home"、vars.selectedTab == "tab_shop"、vars.selectedTab == "tab_task"。
进入预览，点击任意页签即可看到按钮图片和内容区域同步切换。

左键点击时，ChaUI 会先完成自动选中，再执行该按钮的左键脚本。因此左键脚本能读取到新的选择，也可以再次修改同一个变量；如果脚本再次赋值，以脚本最后写入的值为准。右键、中键和悬浮事件不会自动改变选中变量。重复点击已经选中的按钮仍会正常执行左键脚本。

自动选择只属于当前打开的页面。关闭并重新打开页面后，会重新从页面默认变量或服务端下发的变量状态开始，不会把玩家最后一次点击写回页面配置。

完整页签配置示例

yaml

id: tab_demo
version: 1
title: 页签按钮示例
size:
  width: 360
  height: 220
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: true

# 页面打开时默认选中首页。
vars:
  selectedTab: tab_home
  theme: default

# 本示例不使用 PAPI，仍保留完整页面结构。
papi:
  refreshTicks: 20
  values: {}

elements:
  # 首页页签：三个按钮绑定同一个页面变量。
  - id: tab_home
    type: button
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 20
    layout:
      x: 20
      y: 18
      width: 100
      height: 28
    button:
      label: 首页
      font: fonts/menu.ttf
      fontResolution: 64
      color: "#FFE6A3"
      textSize: 1
      textX: 0
      textY: 9
      textLineLength: 0
      textLineWidth: 0
      revealIntervalMs: 0
      align: center
      path: gui/{vars.theme}/tabs/home.png
      gifLoop: true
      gifLoopCount: 0
      sourceX: 0
      sourceY: 0
      sourceWidth: 100
      sourceHeight: 28
      hoverPath: gui/{vars.theme}/tabs/home_hover.png
      hoverGifLoop: true
      hoverGifLoopCount: 0
      hoverSourceX: 0
      hoverSourceY: 0
      hoverSourceWidth: 100
      hoverSourceHeight: 28
      checked: vars.selectedTab
      checkedPath: gui/{vars.theme}/tabs/home_checked.png
      checkedGifLoop: true
      checkedGifLoopCount: 0
      checkedSourceX: 0
      checkedSourceY: 0
      checkedSourceWidth: 100
      checkedSourceHeight: 28
    tooltip:
      - 切换到首页
    events: {}

  # 商店页签。
  - id: tab_shop
    type: button
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 20
    layout:
      x: 130
      y: 18
      width: 100
      height: 28
    button:
      label: 商店
      textSize: 1
      textX: 0
      textY: 9
      textLineLength: 0
      textLineWidth: 0
      revealIntervalMs: 0
      align: center
      path: gui/tabs/shop.png
      gifLoop: true
      gifLoopCount: 0
      sourceX: 0
      sourceY: 0
      sourceWidth: 100
      sourceHeight: 28
      hoverPath: gui/tabs/shop_hover.png
      hoverGifLoop: true
      hoverGifLoopCount: 0
      hoverSourceX: 0
      hoverSourceY: 0
      hoverSourceWidth: 100
      hoverSourceHeight: 28
      checked: vars.selectedTab
      checkedPath: gui/tabs/shop_checked.png
      checkedGifLoop: true
      checkedGifLoopCount: 0
      checkedSourceX: 0
      checkedSourceY: 0
      checkedSourceWidth: 100
      checkedSourceHeight: 28
    tooltip:
      - 切换到商店
    events: {}

  # 任务页签。
  - id: tab_task
    type: button
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 20
    layout:
      x: 240
      y: 18
      width: 100
      height: 28
    button:
      label: 任务
      textSize: 1
      textX: 0
      textY: 9
      textLineLength: 0
      textLineWidth: 0
      revealIntervalMs: 0
      align: center
      path: gui/tabs/task.png
      gifLoop: true
      gifLoopCount: 0
      sourceX: 0
      sourceY: 0
      sourceWidth: 100
      sourceHeight: 28
      hoverPath: gui/tabs/task_hover.png
      hoverGifLoop: true
      hoverGifLoopCount: 0
      hoverSourceX: 0
      hoverSourceY: 0
      hoverSourceWidth: 100
      hoverSourceHeight: 28
      checked: vars.selectedTab
      checkedPath: gui/tabs/task_checked.png
      checkedGifLoop: true
      checkedGifLoopCount: 0
      checkedSourceX: 0
      checkedSourceY: 0
      checkedSourceWidth: 100
      checkedSourceHeight: 28
    tooltip:
      - 切换到任务
    events: {}

  # 只有 selectedTab 等于 tab_home 时显示。
  - id: panel_home
    type: rect
    parent: ""
    visible: true
    enabled: true
    pointerEvents: pass
    opacity: 0.8
    visibleWhen: vars.selectedTab == "tab_home"
    z: 10
    layout:
      x: 20
      y: 60
      width: 320
      height: 140
    rect:
      color: "#36526B"
    tooltip: []
    events: {}

  # 商店内容区域。
  - id: panel_shop
    type: rect
    parent: ""
    visible: true
    enabled: true
    pointerEvents: pass
    opacity: 0.8
    visibleWhen: vars.selectedTab == "tab_shop"
    z: 10
    layout:
      x: 20
      y: 60
      width: 320
      height: 140
    rect:
      color: "#6B5236"
    tooltip: []
    events: {}

  # 任务内容区域。
  - id: panel_task
    type: rect
    parent: ""
    visible: true
    enabled: true
    pointerEvents: pass
    opacity: 0.8
    visibleWhen: vars.selectedTab == "tab_task"
    z: 10
    layout:
      x: 20
      y: 60
      width: 320
      height: 140
    rect:
      color: "#4F366B"
    tooltip: []
    events: {}

脚本读取按钮对象

按钮对象可以读取当前标签、选中绑定和布局公式。若要在点击后检查按钮状态，可以把下面的事件放进对应按钮：

yaml

events:
  leftClick: |-
    vars.clickedLabel = component("tab_home").button.label
    vars.buttonXFormula = component("tab_home").layout.expression("x").source
    log("点击按钮：{vars.clickedLabel}")

常见问题

图片加载成功后为什么没有默认描边

图片按钮使用素材本身的外观；只有图片不可用时才绘制默认按钮背景和描边。

悬浮图片没有切换

检查 hoverPath 的文件位置和大小写。悬浮图片不可用时会继续显示普通图片。

点击后没有显示选中图片

先检查“选中变量”是否写成完整的 vars.<变量名>，再确认变量当前值与按钮 id 完全一致。三个页签按钮必须绑定同一个变量，但各自保留不同的按钮 ID。

鼠标放在已选中的按钮上为什么没有悬浮变化

这是正常行为。选中状态优先于悬浮状态，可以避免当前页签因鼠标经过而看起来像失去选择。

选中图片不存在时会怎样

按钮会显示普通图片，不会改用悬浮图片。自动选中和左键脚本仍然可以正常工作。

左键脚本修改了同一个变量

自动选中先执行，左键脚本后执行。脚本最后写入的值就是本次点击后的最终值。

旧客户端为什么看不到选中状态

旧客户端可能只识别普通和悬浮图片，会忽略新增的选中配置。页面仍可打开，但页签视觉不会完整；使用 checked 页面时应确保玩家使用支持该功能的客户端。

点击脚本没有执行

确认 enabled 与 enabledWhen 允许交互。服务端动作必须先保存页面，再在预览或运行页面中测试。

创建事件

按钮可配置 events.create。页面首次打开时，它会在页面 open 之后执行一次；脚本复制出的新按钮也会各执行一次。适合设置初始选中变量、标签或图片路径。编辑画布不触发，隔离预览会本地触发。

服务端配置文件 ↘

按钮组件 ​

适用场景 ​

通用配置 ​

专属配置 ​

文字配置 ​

普通状态图片 ​

悬浮状态图片 ​

选中状态与选中图片 ​

在编辑器里制作页签按钮 ​

完整页签配置示例 ​

脚本读取按钮对象 ​

常见问题 ​

图片加载成功后为什么没有默认描边 ​

悬浮图片没有切换 ​

点击后没有显示选中图片 ​

鼠标放在已选中的按钮上为什么没有悬浮变化 ​

选中图片不存在时会怎样 ​

左键脚本修改了同一个变量 ​

旧客户端为什么看不到选中状态 ​

点击脚本没有执行 ​

创建事件 ​