猹件开发组

Appearance

On this page

让选项自动切换图片 ​

下拉选择框和点击切换选择框不需要为每个选项增加单独的 image 字段。把选项实际值写入页面变量，再让图片路径读取这个变量，就能让同一套组件皮肤自动切换。

例如难度变量是 easy、normal、hard 时：

yaml
path: gui/difficulty/{vars.difficulty}.png

最终会分别读取：

  • gui/difficulty/easy.png
  • gui/difficulty/normal.png
  • gui/difficulty/hard.png

准备素材 ​

在客户端 resourcepacks/ChaUI/gui/difficulty/ 中准备 easy.png、normal.png、hard.png。文件名应与选项 value 完全一致，并只使用安全的相对目录和受支持图片扩展名。

完整下拉选择框页面 ​

将下面内容保存为 dynamic_dropdown_demo.yml：

yaml
id: dynamic_dropdown_demo
version: 1
title: 动态难度下拉框
size:
  width: 320
  height: 180
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: true
vars:
  difficulty: normal
papi:
  refreshTicks: 20
  values: {}
events:
  open: ""
  close: ""
methods: {}
elements:
  - id: difficulty_dropdown
    type: dropdown
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 10
    layout:
      x: 100
      y: 60
      width: 120
      height: 20
    dropdown:
      bind: vars.difficulty
      maxVisibleOptions: 3
      options:
        - label: 简单
          value: easy
        - label: 普通
          value: normal
        - label: 困难
          value: hard
      textSize: 1
      textX: 6
      textY: 6
      align: center
      color: "#FFFFFF"
      path: gui/difficulty/{vars.difficulty}.png
      hoverPath: gui/difficulty/{vars.difficulty}-hover.png
      openPath: gui/difficulty/{vars.difficulty}-open.png
      optionHoverPath: gui/difficulty/option-hover.png
    events:
      change: |-
        log("难度图片已切换为：{vars.difficulty}")

选择后会先更新 vars.difficulty，当前组件路径随即重新求值并加载对应素材。

完整点击切换页面 ​

将下面内容保存为 dynamic_toggle_demo.yml。准备 day.png、night.png 以及对应的 -hover.png 素材：

yaml
id: dynamic_toggle_demo
version: 1
title: 动态昼夜切换框
size:
  width: 320
  height: 180
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: false
vars:
  theme: day
papi:
  refreshTicks: 20
  values: {}
events:
  open: ""
  close: ""
methods: {}
elements:
  - id: theme_toggle
    type: toggle
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 10
    layout:
      x: 100
      y: 60
      width: 120
      height: 24
    toggle:
      bind: vars.theme
      options:
        - label: 白天主题
          value: day
        - label: 夜晚主题
          value: night
      textSize: 1
      textX: 6
      textY: 8
      align: center
      color: "#FFFFFF"
      path: gui/theme/{vars.theme}.png
      hoverPath: gui/theme/{vars.theme}-hover.png
    events:
      change: |-
        log("主题图片已切换为：{vars.theme}")

为什么无需每项 image 字段 ​

选项只负责表达“显示什么文字、选择后保存什么值”。图片属于组件外观，响应式路径会自动读取当前值。这样同一组选项可以同时控制背景、旁边的图片、文本和其他组件，不必把素材配置重复塞进每一项。

例如旁边的图片组件也可以写：

yaml
image:
  path: gui/difficulty/preview-{vars.difficulty}.png

变量缺失与安全回退 ​

绑定变量缺失或不匹配选项时，选择框只回退显示第一项，不会自动写入变量。此时路径表达式可能得不到可用的最终路径，组件会使用其他可用状态图片或内置样式。

表达式完成后，最终路径仍必须是 ChaUI 素材目录下的安全相对路径。绝对路径、路径穿越、反斜杠、控制字符或不支持的扩展名都会被拒绝，不会读取素材目录外的文件。

常见错误 ​

  • value 使用了中文显示名，但素材使用英文文件名：让实际值与文件名保持一致，label 再写中文。
  • 数字和布尔值直接进入文件名后找不到素材：可以改用稳定的字符串值，例如 low、high。
  • 只准备普通图片却填写了不存在的悬浮路径：删掉悬浮路径即可自然回退普通图片。
  • 在路径中写 ../：最终路径会因不安全而被拒绝。

继续阅读下拉选择框组件和点击切换选择框组件，了解全部选项、浮层与事件行为。