猹件开发组

Appearance

On this page

下拉选择框组件 ​

下拉选择框组件用于在有限空间中选择一个值。关闭时只占 layout.height 指定的一行；点击后，选项会作为页面内最上层的浮层展开，不会挤动后面的组件。

它适合画质、难度、职业、分类等选项较多的设置。每个选项由显示文字 label 和实际值 value 组成，实际值可以是字符串、数字或布尔值。

配置项 ​

配置项类型默认值说明
dropdown.bind字符串新建时为 vars.<组件ID>必须是完整页面变量引用，选择后写入对应变量。
dropdown.options列表一项字符串选项1 至 128 项；value 类型和值的组合不能重复。
dropdown.maxVisibleOptions整数5同时显示 1 至 20 项，更多选项可用滚轮查看。
dropdown.textSize正数或公式1选项文字大小。
dropdown.textX / textY数字或公式6 / 6文字在每一行中的偏移。
dropdown.align字符串leftleft、center、right。
dropdown.color颜色#FFFFFF严格六位 #RRGGBB。
dropdown.path图片路径空关闭状态背景。
dropdown.hoverPath图片路径空关闭状态悬浮背景；不可用时回退普通背景。
dropdown.openPath图片路径空展开状态背景；不可用时回退普通背景。
dropdown.optionHoverPath图片路径空浮层中当前悬浮选项的背景。

每个图片状态都支持对应的 SourceX、SourceY、SourceWidth、SourceHeight 源图选区，以及 GifLoop 和 GifLoopCount。普通状态字段省略状态前缀，例如 sourceX、gifLoop；展开状态使用 openSourceX、openGifLoop，选项悬浮状态使用 optionHoverSourceX、optionHoverGifLoop。循环默认开启，次数默认 0，表示无限循环。

组件根级仍可使用 parent、visible、enabled、pointerEvents、scale、opacity、z、tooltip、layout 和通用鼠标事件。pointerEvents: auto 时，下拉选择框天然参与点击。

完整配置 ​

下面的页面可直接保存为 dropdown_demo.yml。图片字段全部保留，素材不存在时会自动使用内置样式。

yaml
id: 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_select
    type: dropdown
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 10
    tooltip:
      - 选择本次挑战难度
    layout:
      x: 100
      y: 50
      width: 120
      height: 20
    dropdown:
      bind: vars.difficulty
      maxVisibleOptions: 5
      options:
        - label: 简单
          value: easy
        - label: 普通
          value: normal
        - label: 困难
          value: hard
      textSize: 1
      textX: 6
      textY: 6
      align: left
      color: "#FFFFFF"
      path: gui/form/dropdown.png
      gifLoop: true
      gifLoopCount: 0
      sourceX: 0
      sourceY: 0
      sourceWidth: 120
      sourceHeight: 20
      hoverPath: gui/form/dropdown-hover.png
      hoverGifLoop: true
      hoverGifLoopCount: 0
      hoverSourceX: 0
      hoverSourceY: 0
      hoverSourceWidth: 120
      hoverSourceHeight: 20
      openPath: gui/form/dropdown-open.png
      openGifLoop: true
      openGifLoopCount: 0
      openSourceX: 0
      openSourceY: 0
      openSourceWidth: 120
      openSourceHeight: 20
      optionHoverPath: gui/form/dropdown-option-hover.png
      optionHoverGifLoop: true
      optionHoverGifLoopCount: 0
      optionHoverSourceX: 0
      optionHoverSourceY: 0
      optionHoverSourceWidth: 120
      optionHoverSourceHeight: 20
    events:
      change: |-
        log("当前难度：{vars.difficulty}")

玩家选择一项后，ChaUI 会先更新 vars.difficulty，再执行 events.change，所以脚本读取到的是新值。重复选择当前项不会制造额外变化。

展开与滚动 ​

浮层优先向下展开；页面下方空间不足且上方更宽裕时，会自动向上展开。它始终被裁剪在当前 ChaUI 页面范围内。超过 maxVisibleOptions 后，把鼠标放在选项上滚动即可查看其余项目。

点击浮层外部、按下 Esc、隐藏或禁用组件、关闭页面时都会收起。浮层覆盖区域会阻止点击落到后方按钮或原版容器槽位。

在编辑器中配置 ​

  1. 从组件列表添加“下拉选择框”。
  2. 在右侧 176 像素属性栏填写绑定变量和最多显示项数。
  3. 选项先以摘要行显示；点击一项，只展开这一项。
  4. 依次填写“显示文本”“值类型”“值”。值类型可选字符串、数字、布尔值。
  5. 上移、下移和删除各占独立操作行，不需要打开额外窗口。
  6. 进入预览后再测试展开和选择；编辑状态下点击组件只会选中或拖动组件。

半截数字、无法识别的布尔值或重复的“类型 + 值”不会写入页面，修正后再提交即可。选项增删和排序都参与撤销、重做。

不使用图片时 ​

四个路径全部留空即可获得可直接使用的深色选择框、边框、文字与展开箭头。浮层选项也会带基础悬浮高亮，因此可以先完成业务，再补美术素材。

图片皮肤 ​

图片路径相对于 resourcepacks/ChaUI，支持 PNG、JPG、JPEG 和 GIF，也支持响应式路径，例如 gui/difficulty/{vars.difficulty}.png。最终路径变化后会重新加载；GIF 从第 0 帧开始。

各状态可分别裁剪图集。若某个状态图片缺失、路径无效或选区越界，只回退该状态，不会让整个页面关闭。动态选项图片的完整做法见让选项自动切换图片。

常见问题 ​

页面打开后显示第一项，但变量还是旧值 ​

这是安全回退。绑定变量缺失或不匹配任何选项时，只显示第一项，不会偷偷改写变量。玩家真正选择后才写入。

点击后没有展开 ​

检查 visible、enabled 和 pointerEvents。pointerEvents: pass 会让组件完全退出鼠标命中。

浮层被页面边缘截短 ​

这是预期行为。浮层只能出现在页面可视范围内；可移动组件位置、增大页面高度，或减小 maxVisibleOptions。

数字 1 与字符串 "1" 是否相同 ​

不同。选项值按类型比较，这让数字、文字和布尔值可以准确对应业务含义。