滑块（slider）

选择器： slider · 设计器组件： 滑块 · 按名称： slider#名称 或 #名称
用途： 可拖动的数值选择。

硬约束与叠画

1. 控件名来自窗口 XML「名称」；属性赋值无括号（如 标题 = "确定"），方法调用必须带括号（如 刷新()）。
2. 事件写 函数 控件名.事件名(参数…)，形参类型以本页事件表为准。
3. 任意控件客户区叠画用支持库 绘制类：绘制类 g → g.绑组件(本控件名)（组件名无引号）。画布场景编辑见 画布控件。
4. 字体对象见绘制文档中的字体类；置字体(字体类) 将字体应用到本控件。
5. 不要虚构未列出的方法；YSS 键见下文与 YSS.md。

属性

设计器属性面板与代码侧可读可写属性（来源：组件类库）。

属性	类型	读写	说明
提示	文本	读写	鼠标悬停时的提示文字
鼠标指针	文本	读写	空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如 资源/press.cur）
左边	小数	读写	相对窗体左边的位置（像素）
顶边	小数	读写	相对窗体顶边的位置（像素）
宽度	小数	读写	控件宽度（像素）
高度	小数	读写	控件高度（像素）
停靠	整数	读写	0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附
可见	逻辑	读写	真=显示，假=隐藏
启用	逻辑	读写	真=可用，假=禁用
句柄	长整数	只读	组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读
值	整数	读写	当前数值（在最小值与最大值之间）
当前值	整数	读写	同「值」；当前数值（在最小值与最大值之间）
最小值	整数	读写	数值范围下限
最大值	整数	读写	数值范围上限
步长	整数	读写	每次增减的步进值
轨道背景色	文本	读写	如 #RRGGBB
轨道填充色	文本	读写	滑块已选区颜色
滑块色	文本	读写	滑块圆点颜色
显示文本	逻辑	读写	真=显示数值文本
显示为百分比	逻辑	读写	真=按百分比显示
显示小数	逻辑	读写	真=显示小数位
小数位数	整数	读写	1-6，启用小数时有效
文本位置	整数	读写	0左 1上 2右 3下 4组件上
透明背景	逻辑	读写	真=滑块无底板背景
悬停展开	逻辑	读写	真=收起为细轨，悬停/拖动才展开圆点（播放器音量条风格）
圆角	整数	读写	像素，0=直角
显示边框	逻辑	读写	真=显示边框
边框大小	整数	读写	像素
边框颜色	文本	读写	如 #RRGGBB
描边样式	整数	读写	0=实线…4=双点划线

方法

组件类库方法（调用必须带括号）。下表为带类型签名。

方法	签名	返回	说明
置值	无 置值(整数 数值)	无	也可属性 值 / 当前值
取值	整数 取值()	整数
移动	无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度])	无	可选同时改宽高
置焦点	无 置焦点()	无
刷新	无 刷新()	无	立即重绘所在窗口
显示 / 隐藏	无 显示() / 无 隐藏()	无	等同 可见 = 真/假
置字体	逻辑 置字体(字体类 字体)	逻辑	见 painter.md

滑块1.置值(50)
输出(滑块1.取值())

事件

在代码中写 函数 控件名.事件名(...) 处理。

事件	参数	说明
单击	整数 X, 整数 Y	鼠标左键单击控件。
双击	整数 X, 整数 Y	鼠标左键双击控件。
右键单击	整数 X, 整数 Y	鼠标右键单击控件。
鼠标按下	整数 X, 整数 Y, 逻辑 按下	鼠标键在控件上按下。按下=真表示当前仍按住。
鼠标抬起	整数 X, 整数 Y, 逻辑 按下	鼠标键在控件上放开。
鼠标移动	整数 X, 整数 Y, 逻辑 按下	鼠标在控件上移动。按下表示左键是否按住。
鼠标进入	整数 X, 整数 Y	鼠标指针进入控件区域。
鼠标离开	整数 X, 整数 Y	鼠标指针离开控件区域。
鼠标左键单击	整数 X, 整数 Y	鼠标左键单击（与「单击」同时触发）。
鼠标左键双击	整数 X, 整数 Y	鼠标左键双击（与「双击」同时触发）。
鼠标中间单击	整数 X, 整数 Y	鼠标中键单击控件。
鼠标齿轮滚动	整数 X, 整数 Y, 逻辑 向上	在控件上滚动鼠标滚轮。向上=真表示向上滚。
鼠标右键单击	整数 X, 整数 Y	鼠标右键单击（与「右键单击」同时触发）。
鼠标右键双击	整数 X, 整数 Y	鼠标右键双击控件。
值改变	整数 当前值	当前数值发生变化时触发（拖动滑块、程序置值等）。
滑块按下	无	在滑块上按下鼠标左键时触发（开始拖动）。
滑块松开	整数 当前值	在滑块上拖动后松开鼠标左键时触发。

函数 滑块1.单击 (整数 X, 整数 Y) {
    // …
}

YSS 样式

以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。

样式概览

YSS 控制轨道 groove、已滑过段 track fill、滑块圆点 handle 与可选数值文字。

伪状态与映射

子控件： slider:groove（轨道） · slider:handle（滑块圆点）

子控件映射（ 必读）：

在子控件块中写的键	实际落到控件的字段
slider:groove { background-color }	轨道色 → background-color（backColor）
slider:handle { background-color }	滑块圆点色 → thumb-color（pressedForeColor）

已滑过段（track fill）与进度条共用双色槽：起始色 + 结束色 可组成渐变。

颜色槽对照（ 必读）：

视觉部位	推荐键	内部字段
轨道 groove / 未滑过段	background-color	backColor
已滑过段 fill 起始	background-gradient-color	backColor2
已滑过段 fill 结束	pressed-background-color	pressedBackColor
滑块 handle	thumb-color	pressedForeColor

属性说明（逐键）

下表按「数值 → 轨道 groove → 已滑过段 fill → 滑块 handle → 文字 → 外壳」展开。每条写清：作用、取值、绘制时机、注意点。

数值与范围

属性	作用	取值 / 范围	说明与注意
value / current-value	当前值	数值	拖动圆点改变；YSS 可设初始预览值。
min / minimum	最小值	数值	默认习惯与进度类控件相同（约 0）。
max / maximum	最大值	数值	默认约 100；须 max > min。

轨道（groove）

属性	作用	取值 / 范围	说明与注意
background-color / background	轨道 / 未滑过段底色	颜色，如 #3A3A40	映射 backColor；绘制细条轨道（高度≈核心区高的 22%，clamp 4–6px）及（非透明时）整块底板。
slider:groove { background-color }	同上（子选择器）	颜色	与基选择器 background-color 等价。
border-radius	轨道 / 底板圆角	像素，如 8	影响轨道条与背景区圆角。
transparent-background	不绘制控件底板	true / false	true 时仍绘制细轨道条与圆点 handle；适合「仅条+点」极简风。

绘制顺序： 非透明时先画整块底板 → 再画全长细轨道条（groove）→ 再画已滑过 fill → 最后画 handle 圆点。

已滑过段（track fill）

属性	作用	取值 / 范围	说明与注意
background-gradient-color	已滑过段起始色	颜色，如 #007ACC	映射 backColor2；从 min 端到当前 thumb 位置。
pressed-background-color	已滑过段结束色	颜色，如 #00B4FF	与起始色不同时沿 background-gradient-direction 绘制填充渐变。
background-gradient-direction	填充渐变方向	horizontal/1 · vertical/0（默认）	水平滑块常用 horizontal。

若仅设 background-gradient-color 而未设 pressed-background-color（或两者同色），已滑过段为纯色。

fill 宽度 = 比例 × 轨道宽，最小宽度约等于轨道条高度以保证小比例时可见。

滑块圆点（handle / thumb）

属性	作用	取值 / 范围	说明与注意
thumb-color	滑块圆点颜色	颜色，如 #FFFFFF	映射 pressedForeColor；拖动热点在圆心。
slider:handle { background-color }	同上（子选择器）	颜色	与 thumb-color 等价。
reveal-on-hover / hover-reveal / expand-on-hover	悬停才展开	true/false	复用 showHotkeyUnderline；收起时细轨+隐圆点，命中区仍是整控件。

handle 几何（运行时/设计器，非 YSS 键）：

量	说明
形状	圆形
直径	≈核心区高的 72%，clamp 约 12–18px
位置	水平位置 = min 端 + 比例 × 轨道宽，圆心对齐

YSS 暂无独立 handle-size 键。

数值文字（若显示）

属性	作用	取值 / 范围	说明与注意
show-text	是否显示数值	true / false	与进度条共用 allowCopy 槽；文字位置由内部 textPos 决定，YSS 暂无独立 text-position 键。
percent / show-percent	按百分比显示	true / false
color	旁侧数值文字颜色	颜色，如 #CCCCCC
font-size	数值字号	像素
font-family	数值字体族	字符串
font-bold / font-italic	粗体 / 斜体	true / false

外壳边框与边距

属性	作用	取值 / 范围	说明与注意
show-border	是否画外边框	true / false	包裹整个滑块控件区。
border-color	外边框色	颜色
border-width	外边框宽	像素
margin / margin-left / margin-top / margin-right / margin-bottom	绘制区域外边距	像素 / 简写	在控件矩形内缩进轨道与 handle。

滑块无焦点环绘制（与进度条不同）；拖动时触发「值改变」事件。

---

使用示例

极简透明轨 + 纯色 fill

slider#滑块1 {
    background-color: #3A3A40;
    background-gradient-color: #007ACC;
    thumb-color: #FFFFFF;
    transparent-background: true;
    border-radius: 8;
}

双色渐变 fill + 子选择器

slider#滑块1 {
    background-gradient-color: #007ACC;
    pressed-background-color: #00B4FF;
    background-gradient-direction: horizontal;
    thumb-color: #FFFFFF;
    transparent-background: true;
}

slider:groove {
    background-color: #3A3A40;
}

slider:handle {
    background-color: #FFFFFF;
}

带边框与边距

slider#滑块1 {
    background-color: #2D2D30;
    background-gradient-color: #5B6FE8;
    thumb-color: #FFFFFF;
    show-border: true;
    border-color: #5A5A5A;
    border-width: 1;
    margin: 2;
    color: #CCCCCC;
}

预设初值与范围

slider#音量 {
    value: 40;
    min: 0;
    max: 100;
    background-color: #404040;
    background-gradient-color: #00B4FF;
    thumb-color: #FFFFFF;
    transparent-background: true;
}

显示百分比

slider#进度滑块 {
    value: 75;
    min: 0;
    max: 100;
    show-text: true;
    percent: true;
    background-color: #3A3A40;
    background-gradient-color: #5B6FE8;
    thumb-color: #FFFFFF;
    color: #CCCCCC;
    transparent-background: true;
}

---

完整示例

slider#滑块1 {
    background-color: #3A3A40;
    background-gradient-color: #007ACC;
    pressed-background-color: #00B4FF;
    background-gradient-direction: horizontal;
    thumb-color: #FFFFFF;
    transparent-background: true;
    border-radius: 8;
    color: #CCCCCC;
    show-border: false;
    margin: 2;
    value: 40;
    min: 0;
    max: 100;
}

slider:groove {
    background-color: #3A3A40;
}

slider:handle {
    background-color: #FFFFFF;
}

---