猹件开发组

Appearance

On this page

拖动条组件 ​

拖动条组件让玩家在最小值和最大值之间选择数字，适合音量、透明度、数量、缩放与灵敏度。它支持横向和纵向轨道，并按 step 把结果吸附到合法刻度。

配置项 ​

配置项类型默认值说明
slider.bind字符串新建时为 vars.<组件ID>完整页面变量引用。
slider.min数字或公式0最小值。
slider.max数字或公式100最大值，必须大于最小值。
slider.step正数或公式1每次变化的最小刻度。
slider.orientation字符串horizontalhorizontal 或 vertical。
slider.thumbWidth正数或公式8滑块宽度。
slider.thumbHeight正数或公式16滑块高度。
slider.trackPath图片路径空整条轨道图片。
slider.fillPath图片路径空已填充部分图片，会按比例裁剪。
slider.thumbPath图片路径空滑块图片。
slider.thumbHoverPath图片路径空滑块悬浮图片；不可用时回退普通滑块。

四种图片都支持对应的源图选区、GifLoop 和 GifLoopCount。例如轨道使用 trackSourceX、trackGifLoop，填充使用 fillSourceWidth，滑块悬浮使用 thumbHoverSourceHeight。循环默认开启，次数默认 0。

完整配置 ​

yaml
id: slider_demo
version: 1
title: 拖动条示例
size:
  width: 340
  height: 180
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: true

vars:
  volume: 60

papi:
  refreshTicks: 20
  values: {}

events:
  open: ""
  close: ""

methods: {}

elements:
  - id: volume_slider
    type: slider
    parent: ""
    visible: true
    enabled: true
    pointerEvents: auto
    scale: 1
    opacity: 1
    z: 10
    tooltip:
      - 拖动调节音量
    layout:
      x: 70
      y: 70
      width: 200
      height: 16
    slider:
      bind: vars.volume
      min: 0
      max: 100
      step: 5
      orientation: horizontal
      thumbWidth: 10
      thumbHeight: 16
      trackPath: gui/form/slider-track.png
      trackGifLoop: true
      trackGifLoopCount: 0
      trackSourceX: 0
      trackSourceY: 0
      trackSourceWidth: 200
      trackSourceHeight: 16
      fillPath: gui/form/slider-fill.png
      fillGifLoop: true
      fillGifLoopCount: 0
      fillSourceX: 0
      fillSourceY: 0
      fillSourceWidth: 200
      fillSourceHeight: 16
      thumbPath: gui/form/slider-thumb.png
      thumbGifLoop: true
      thumbGifLoopCount: 0
      thumbSourceX: 0
      thumbSourceY: 0
      thumbSourceWidth: 10
      thumbSourceHeight: 16
      thumbHoverPath: gui/form/slider-thumb-hover.png
      thumbHoverGifLoop: true
      thumbHoverGifLoopCount: 0
      thumbHoverSourceX: 0
      thumbHoverSourceY: 0
      thumbHoverSourceWidth: 10
      thumbHoverSourceHeight: 16
    events:
      input: |-
        vars.volumeText = "音量：{vars.volume}%"
      change: |-
        log("最终音量：{vars.volume}")

input 与 change ​

拖动过程中，每跨过一个 step，ChaUI 会先更新绑定变量，再触发一次 events.input。松开滑块时只触发一次 events.change。直接点击轨道跳转时，顺序是更新变量 → input → change。

因此，input 适合刷新本地文字和预览效果；change 适合提交结果或执行服务端动作，避免拖动时高频提交。

开始拖动时会固定本次操作使用的最小值、最大值和步长，防止公式在拖动中改变后让滑块跳动。下一次按下会读取新范围。

在编辑器中配置 ​

  1. 添加“拖动条”，填写绑定变量、最小值、最大值和步长。
  2. 选择横向或纵向，并调整滑块宽高。
  3. 图片皮肤字段按轨道、已填充、滑块、滑块悬浮四组纵向排列。
  4. 把连续预览写入 events.input，把最终提交写入 events.change。
  5. 进入预览后拖动；编辑模式不会修改变量。

不使用图片时 ​

所有图片路径留空时，会显示基础轨道、已填充颜色、滑块和悬浮描边。横向、纵向和事件行为都完整可用。

图片皮肤 ​

填充图片不是把整张纹理压扁到短区域，而是同时裁剪显示区域和源图区域，因此条纹、渐变和边缘不会被横向挤压。纵向拖动时按高度裁剪。

路径可包含响应式表达式，源图字段可填写公式。某个状态不可用时只回退该状态；thumbHoverPath 不可用时会继续显示 thumbPath。

常见问题 ​

拖动时服务端动作执行太频繁 ​

把提交型动作从 events.input 移到 events.change。input 本来就是连续预览事件。

变量超出范围 ​

显示时会按最小值和最大值夹取，但不会仅因渲染而改写变量；玩家操作后才写入合法刻度值。

滑块完全不动 ​

检查 max 是否大于 min、step 是否为正数，以及运行时公式能否得到有限数字。

纵向方向与预期相反 ​

纵向拖动条默认上方表示最大值、下方表示最小值，这与常见音量推子一致。