进度条控件 (SProgress)¶

Warning

The current page still doesn't have a translation for this language.

You can read it through google translate.

进度条是用于显示操作或任务进度的可视化控件，支持水平和垂直两种方向，以及多种显示样式。

基本信息¶

类名：SProgress
控件标签：progress
基类：SWindow
功能：显示进度信息

属性说明¶

自身属性¶

属性名	类型	默认值	说明
bkgndSkin	skin	系统内置皮肤	背景（轨道）皮肤。未指定时自动使用内置的 `SKIN_SYS_PROG_BKGND` / `SKIN_SYS_VERT_PROG_BKGND`
trackSkin	skin	系统内置皮肤	`bkgndSkin` 的同义属性，同样写入背景皮肤
posSkin	skin	系统内置皮肤	前景（已填充部分）皮肤。未指定时自动使用内置的 `SKIN_SYS_PROG_BAR` / `SKIN_SYS_VERT_PROG_BAR`
filledSkin	skin	系统内置皮肤	`posSkin` 的同义属性，同样写入前景皮肤
waveSkin	skin	-	波动特效皮肤。指定后控件会注册时间线处理器，在已填充区域内循环绘制一层流动的特效
min	int	0	进度最小值
max	int	100	进度最大值
range	string	-	一次性设置范围，格式 `"min,max"`，例如 `range="0,200"`，等价于同时设置 `min` 与 `max`
value	int	0	当前进度值
vertical	bool	false	是否垂直显示（`0` 水平，`1` 垂直）
showText	bool	false	是否显示百分比文字。仅在水平进度条上绘制，格式如 `50%`

属性名是 showText，不是 showPercent

旧文档中的 showPercent 在源码中并不存在，实际属性名为 showText。 SProgress 也没有 colorBkgnd/colorPos 属性，进度条的颜色由 bkgndSkin/posSkin 皮肤决定。

继承自 SWindow / SwndStyle / 布局参数的通用属性，见通用属性。

使用示例¶

基本进度条¶

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

垂直进度条¶

<progress name="progressVertical" 
          pos="10,40,30,140" 
          vertical="1" 
          value="75"/>

带百分比显示的进度条¶

<progress name="progressPercent" 
          pos="10,150,210,170" 
          value="30"
          showText="1"/>

自定义皮肤的进度条¶

<progress name="progressStyled" 
          pos="10,180,210,200" 
          value="60"
          bkgndSkin="skin_progress_bkgnd"
          posSkin="skin_progress_pos"/>

带波动特效的进度条¶

<progress name="progressWave" 
          pos="10,210,210,230" 
          value="60"
          range="0,100"
          waveSkin="skin_progress_wave"/>

事件处理¶

进度条控件通常作为显示控件使用，较少触发事件。但可以通过代码监听值变化：

// 事件处理示例
void UpdateProgress(int nValue)
{
    SProgress *pProgress = FindChildByName2<SProgress>(L"progressBasic");
    if(pProgress)
    {
        pProgress->SetValue(nValue);
    }
}

代码操作¶

// 查找进度条控件
SProgress *pProgress = FindChildByName2<SProgress>(L"progressBasic");

// 设置进度值
pProgress->SetValue(75);

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

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

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

最佳实践¶

合理设置范围：根据实际需要设置合适的 min 和 max 值
适时更新：在长时间操作中定期更新进度值，给用户良好反馈
视觉反馈：使用 showPercent 属性显示具体数值
皮肤定制：通过 bkgndSkin 和 posSkin 属性定制外观

常见问题¶

Q: 进度条不显示百分比怎么办？¶

A: 检查是否设置了 showPercent 属性为 1。

Q: 进度条显示异常怎么办？¶

A: 确保 value 在 min 和 max 范围内。

Q: 垂直进度条方向不对怎么办？¶

A: 检查 vertical 属性是否设置为 1。