跳转至

滑块控件 (SSliderBar)

滑块是一种可以通过拖动来调节数值的控件，常用于音量控制、亮度调节等场景。支持水平和垂直两种方向。

基本信息

  • 类名：SSliderBar
  • 控件标签：sliderbar
  • 基类：SProgress
  • 功能：提供可拖动的数值调节

属性说明

SSliderBar 继承自 SProgress，先列出自身属性，再说明继承自 SProgress 的属性。

自身属性

属性名 类型 默认值 说明
thumbSkin string SKIN_SYS_SLIDER_THUMB 滑块皮肤
thumbInRail bool false 滑块是否限制在轨道内
drawRail bool true 是否绘制轨道背景
drawValue bool true 是否在轨道中绘制已填充部分
dragTip bool false 拖动时是否在滑块旁显示数值提示
animate bool true 拖动时滑块是否带透明度动画
sepColor color #000000 轨道分隔线颜色
thumb:xxx - - 以 thumb: 前缀设置滑块动画器（SByteAnimator）属性，如 thumb:duration
value:xxx - - 以 value: 前缀设置值动画器（SByteAnimator）属性

继承自 SProgress 的属性

属性名 类型 默认值 说明
min int 0 最小值
max int 100 最大值
value int 0 当前值
vertical bool false 是否垂直（true-垂直，false-水平）
bkgndSkin / trackSkin string - 背景/轨道皮肤（二者等价，均映射到背景皮肤）
posSkin / filledSkin string - 已填充部分皮肤（二者等价）
showText bool false 是否在滑块中心显示当前值文本

字体、颜色、可用、可见等通用属性见通用属性。

使用示例

基本滑块

<sliderbar name="sliderBasic" 
           pos="10,10,210,30" 
           value="50"
           min="0"
           max="100"/>

垂直滑块

<sliderbar name="sliderVertical" 
           pos="10,50,30,200" 
           vertical="1" 
           value="75"/>

限制滑块范围的滑块

<sliderbar name="sliderRail" 
           pos="10,210,210,230" 
           value="30"
           thumbInRail="1"/>

自定义皮肤的滑块

<sliderbar name="sliderStyled" 
           pos="10,240,210,260" 
           value="60"
           thumbSkin="skin_slider_thumb"
           bkgndSkin="skin_slider_bkgnd"
           posSkin="skin_slider_pos"/>

事件处理

滑块控件支持以下事件：

事件名 EventID 说明
EVT_SLIDER_POS EventSliderPos::EventID 滑块位置变化事件 
// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"sliderBasic", EventSliderPos::EventID, OnSliderPosChanged)
EVENT_MAP_END()

void OnSliderPosChanged(IEvtArgs *pEvt)
{
    EventSliderPos *pRealEvt = sobj_cast<EventSliderPos>(pEvt);
    int nPos = pRealEvt->nPos;
    // 处理滑块位置变化
}

数值控制

代码操作

// 查找滑块控件
SSliderBar *pSlider = FindChildByName2<SSliderBar>(L"sliderBasic");

// 设置当前值
pSlider->SetValue(75);

// 获取当前值
int nValue = pSlider->GetValue();

// 设置范围
pSlider->SetRange(0, 200);

// 获取范围
int nMin, nMax;
pSlider->GetRange(&nMin, &nMax);

样式定制

基本样式

<style>
    <class name="sliderStyle"
           bkgndSkin="slider_bg"
           channelSkin="slider_channel"
           thumbSkin="slider_thumb"
           showTip="1"/>
</style>

<sliderbar class="sliderStyle"
           value="50"/>

自定义提示

<sliderbar tipFormat="Level: %d"
           showTip="1"/>

最佳实践

  1. 合理设置范围：根据实际需要设置合适的 min 和 max 值
  2. 视觉反馈：通过不同皮肤区分滑块的不同状态
  3. 交互体验：使用 thumbInRail 属性控制滑块移动范围
  4. 方向选择：根据界面布局选择合适的 vertical 方向

常见问题

拖动不流畅

  • 检查步进值设置
  • 确认事件处理逻辑
  • 验证性能瓶颈

滑块皮肤显示异常怎么办？

A: 检查 thumbSkin、bkgndSkin 和 posSkin 是否正确设置。

相关控件