跳到主要内容

进度条 ProgressBar

进度条是最直观的“任务还剩多少”的表达方式。HiEasyX 的 ProgressBar 支持带文字标签和不带标签两种风格，颜色也可以完全自定义，非常适合加载画面、文件拷贝、游戏血条等场景。

函数原型​

ProgressBar 提供了三个重载，从简到繁任你选择：

// 极简版：只给进度和尺寸
void ProgressBar(float Fraction, HXPoint Size = {-1, 22});

// 进阶版：额外控制颜色等属性
void ProgressBar(float Fraction, HXPoint Size, ProgressBarProfile &Profile);

// 完整版：带上文字标签
void ProgressBar(const HXString &Title, float Fraction, HXPoint Size = {-1, 22});

参数说明​

通用参数​

参数类型默认值说明
Fractionfloat—当前进度，范围 0.0f ~ 1.0f。小于 0 视为 0，大于 1 视为 1。
SizeHXPoint{-1, 22}进度条的宽高。{-1, 22} 表示宽度自动填充父容器，高度 22 像素。
TitleHXString—（仅第三个重载）显示在进度条左侧的标签文字，例如 HXStr("下载中")。

ProgressBarProfile​

当你需要自定义颜色时，传入这个资料结构体：

字段类型默认值说明
FontSizeint14标签文字的字体大小（仅带标签时有效）。
Heightint6进度条轨道本身的粗细，单位像素。
FillColorHXColor主题强调色已填充部分的颜色。不设置则跟随当前主题。
TrackColorHXColor主题背景色未填充轨道的颜色。
BorderColorHXColor主题边框色进度条外边框颜色。
什么时候用哪个重载？
  • 只需要一个血条或加载条 → 用第一个重载，一行搞定。
  • 想改变颜色以匹配你的游戏主题 → 用第二个重载，传入自定义 Profile。
  • 需要让用户知道“这是什么进度” → 用第三个重载，加个标签。

返回值​

void。进度条是纯展示控件，不产生交互状态。

完整示例​

#include <include/hex.h>
#include <include/impl/EasyX/hex_impl_easyx.h>

static float g_downloadProgress = 0.0f;
static HX::ProgressBarProfile g_profile;

int main() {
    static HX::WindowProfile wp;
    // 自定义一个“赛博朋克绿”风格
    g_profile.FillColor = HX::HXColor{0, 255, 128, 255};
    g_profile.TrackColor = HX::HXColor{30, 30, 30, 255};
    g_profile.Height = 8;

    while (true) {
        HX::HXBegin();
        ExMessage msg;
        while (peekmessage(&msg)) {
            HX::PushMessage(HX::GetHXMessage(&msg));
        }

        HX::Window(HXStr("ProgressBar 示例"), wp);

        // 1. 极简进度条
        HX::Text(HXStr("极简风格："));
        HX::ProgressBar(g_downloadProgress);

        // 2. 自定义颜色的进度条
        HX::Text(HXStr("自定义颜色："));
        HX::ProgressBar(g_downloadProgress, {-1, 22}, g_profile);

        // 3. 带标签的进度条
        HX::Text(HXStr("带文字标签："));
        HX::ProgressBar(HXStr("正在下载资源包"), g_downloadProgress);

        // 模拟下载进度
        if (g_downloadProgress < 1.0f) {
            g_downloadProgress += 0.002f;
        }

        HX::End();
        HX::Render();

        Sleep(16); // 约 60 FPS
    }

    return 0;
}

颜色自定义详解​

进度条由三部分组成，你可以分别控制它们的颜色：

g_profile.FillColor   = HX::HXColor{255, 100, 100, 255}; // 已填充：红色
g_profile.TrackColor  = HX::HXColor{50, 50, 50, 255};    // 背景：深灰
g_profile.BorderColor = HX::HXColor{200, 200, 200, 255}; // 边框：浅灰

如果不指定，它们会自动从当前主题中取值，保持界面风格统一。

关于高度

Profile.Height 控制的是进度条轨道的高度，而整个控件占据的高度由 Size.y 决定。也就是说，Size.y 要大于等于 Height 加上必要的内边距，否则文字可能会被截断。

常见疑问​

Q：进度可以反向走吗（比如血量减少）？ 可以。Fraction 从 1.0f 降到 0.0f 时，填充条会自然缩短，没有任何限制。

Q：怎么显示百分比数字？ 第三个重载只显示固定标签。如果你需要在进度条内部显示 85%，可以结合 Text 控件手动拼接字符串：

HXString label = HXStr("下载中 ") + std::to_wstring(int(g_downloadProgress * 100)) + HXStr("%");
HX::ProgressBar(label, g_downloadProgress);

运行效果​

截图占位符：请补充 $name 控件的运行效果截图。

截图占位符：请补充 ProgressBar 运行效果 的运行效果截图，保存为 ./assets/ProgressBar_view.png。`n