猹件开发组

Appearance

On this page

点击切换选择框组件 ​

点击切换选择框组件会在每次有效左键点击时选择下一项，最后一项之后回到第一项。它的操作感觉与编辑器中的点击切换控件一致，适合开关、循环模式、排序方式和少量枚举选项。

配置项 ​

配置项类型默认值说明
toggle.bind字符串新建时为 vars.<组件ID>必须是完整页面变量引用。
toggle.options列表关闭=false、开启=true1 至 128 项，按列表顺序循环。
toggle.textSize正数或公式1当前选项文字大小。
toggle.textX / textY数字或公式6 / 6文字在组件内的偏移。
toggle.align字符串leftleft、center、right。
toggle.color颜色#FFFFFF严格六位 #RRGGBB。
toggle.path图片路径空普通背景。
toggle.hoverPath图片路径空悬浮背景；不可用时回退普通背景。

普通和悬浮图片分别支持源图选区与 GIF 字段：sourceX/Y/Width/Height、gifLoop、gifLoopCount，以及 hoverSourceX/Y/Width/Height、hoverGifLoop、hoverGifLoopCount。循环默认 true，次数默认 0。

完整配置 ​

yaml
id: toggle_demo
version: 1
title: 点击切换选择框示例
size:
  width: 320
  height: 180
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: true

vars:
  music: true

papi:
  refreshTicks: 20
  values: {}

events:
  open: ""
  close: ""

methods: {}

elements:
  - id: music_toggle
    type: toggle
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 10
    tooltip:
      - 点击切换音乐状态
    layout:
      x: 108
      y: 60
      width: 104
      height: 20
    toggle:
      bind: vars.music
      options:
        - label: 音乐：关闭
          value: false
        - label: 音乐：开启
          value: true
      textSize: 1
      textX: 6
      textY: 6
      align: center
      color: "#FFFFFF"
      path: gui/form/toggle.png
      gifLoop: true
      gifLoopCount: 0
      sourceX: 0
      sourceY: 0
      sourceWidth: 104
      sourceHeight: 20
      hoverPath: gui/form/toggle-hover.png
      hoverGifLoop: true
      hoverGifLoopCount: 0
      hoverSourceX: 0
      hoverSourceY: 0
      hoverSourceWidth: 104
      hoverSourceHeight: 20
    events:
      change: |-
        log("音乐开关：{vars.music}")

有效左键点击会先把下一项的值写入 vars.music，再执行 events.change。右键、中键、按下、松开和悬浮事件不会自动切换选项。

在编辑器中配置 ​

  1. 添加“点击切换框”。新组件默认已有“关闭”和“开启”两个布尔选项。
  2. 在右侧属性栏修改绑定变量。
  3. 点击选项摘要，只纵向展开当前项；依次编辑文字、值类型和值。
  4. 使用独立的上移、下移、删除操作调整循环顺序。
  5. 进入预览后左键测试。编辑状态只负责选中与拖动，不会修改变量。

不使用图片时 ​

留空 path 与 hoverPath 会显示基础背景、边框和当前选项文字。内置悬浮反馈会继续工作。

图片皮肤 ​

普通与悬浮背景使用 ChaUI 素材相对路径，支持响应式 {...}、源图选区和 GIF。悬浮图片不可用时回退普通图片，普通图片也不可用时回退内置样式。

如果希望不同选项显示不同图片，可以让路径读取绑定变量，例如 gui/music/{vars.music}.png。完整示例见让选项自动切换图片。

常见问题 ​

第一次点击没有从当前画面继续 ​

当变量缺失或值不在选项中时，画面只回退显示第一项；第一次点击会正式选择第一项。它不会在渲染时自动改变量。

点击一次跳过了一个选项 ​

确认页面上没有两个重叠的切换组件同时绑定同一变量，也不要在 events.change 中再次手动切换同一变量。

布尔值写成了字符串 ​

true 与 false 不加引号才是布尔值；"true" 是字符串。编辑器选择“布尔值”类型可以避免混淆。