Slider

Slider 允许通过拖动一个滑块（knob）在区间 [min, max] 内选择一个 float 值。它可以是连续的或离散的（带步进，通过 npos）。方向会自动检测：如果 宽度 ≥ 高度 则为水平，否则为垂直。触摸滑块之外的位置会平滑地动画到所触摸的点；拖动则持续更新值。

🟢 · 包： dev.crossfly.ui · 继承： Component · 样式： SliderStyle（带按下变体 sliderPressed()）

何时使用

连续或近似的值：音量、亮度、区间、缩放。
用 npos 在少量离散步进中选择（例如 1 到 5）。

何时不使用

当用户需要输入一个精确的数字时 → 使用数字模式的 textfield。

外观

一条分为两段的条 —— 已填充（滑块之前）和未填充（之后）—— 加上滑块。每一段的坐标（bx1/by1/bw1/bh1、bx2/by2/bw2/bh2）和滑块的坐标（kx/ky/ks）在布局时计算（全部为 float）。条的粗细为 thickness * fontHeight；滑块为 knobSize * fontHeight（来自 SliderStyle）。

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      Label saida = new Label("Volume: 50");
      add(LAY_AUTO, saida);

      // 连续 Slider 0..100，从 50 开始；onAction 在每次 value 变化时触发
      Slider volume = new Slider(0, 100, 50);
      volume.onAction(c -> saida.setText("Volume: " + (int) volume.value));
      add(LAY_AUTO, volume);
   }
}

下面的片段只展示核心部分（放入 onShow() 内的内容）。要运行它们，请将它们放入上面的 MainWindow 骨架中。

基本用法

Slider volume = new Slider(0, 100, 50);                 // 连续，从 50 开始
volume.onAction(c -> System.out.println("valor: " + volume.value));
container.add(LAY_AUTO, volume);

构造函数

构造函数	描述
`Slider(float min, float max, float value)`	连续型 slider。
`Slider(float min, float max, float value, int npos)`	离散型 slider：`npos` 个位置（例如 `5` → 步进在 0%、25%、50%、75%、100%）。

属性与自定义

属性 / 方法	类型	默认值	作用
`value`	`float`（字段）	构造函数	当前值（只读）。
`min` / `max`	`float`（字段）	构造函数	区间的边界。
`npos`	`int`（字段）	`0`	离散位置数；`0` = 连续。
`setValue(float)`	`void`	—	立即设置值（= `setValue(v, false)`）；应用 `clamp` + `snap`。
`setValue(float, boolean animated)`	`void`	—	带/不带动画地设置值；触发 `runActions()`。

回调与事件

回调	何时触发
`onAction(Action)`	每次 `value` 变化时（拖动、点击动画和 `setValue`）。

状态

dragging：当用户拖动滑块时（onPan），value 随每次移动而更新。
tap-to-jump：触摸滑块之外的位置会动画到所触摸的点（PositionAnimation，持续时间 style.animationDuration）。
pressed：使用其自有的按下样式（sliderPressed()）。

带 5 个档位的离散型 slider

Slider nivel = new Slider(0, 100, 50, 5);               // 步长：0,25,50,75,100
nivel.onAction(c -> System.out.println("nível: " + nivel.value));
container.add(LAY_AUTO, nivel);

nivel.setValue(75, true);   // 动画到 75（会 snap 到最近的步长）

最佳实践

传入一个位于 [min, max] 内的初始 value：构造函数不做 clamp（只有 setValue 做）。
要强制垂直方向，在布局中给 slider 的高度大于宽度。

常见错误

假设方向固定：它是在布局时由宽高比决定的。
在 npos > 0 时期待连续值：在离散模式下，值总是被“吸附”到步进上。

另见

领域指南：ui/ · 食谱：cookbook/
概念（布局与响应式）：concepts/
相关组件：progress