Skip to content

progressbar

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

progressbar

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
assets/shaders
assets/shaders
 
 
CMakeLists.txt
CMakeLists.txt
 
 
README.md
README.md
 
 
progressbar.cpp
progressbar.cpp
 
 

README.md

ProgressBar Component - 进度条组件

组件类型: 进度显示控件
版本: v0.0.1
作者: Bit HCI Team

📋 概述

ProgressBar 是一个可视化进度显示组件，支持平滑动画和多种控制模式，展示了值的映射、动画插值和状态管理。

特性

  • ✅ 平滑动画: 进度变化使用平滑过渡效果
  • ✅ 多种模式: 手动控制、自动循环、自动一次
  • ✅ 实时反馈: 显示当前进度百分比
  • ✅ 键盘控制: 支持模式切换、重置、手动调节
  • ✅ 简洁设计: 使用矩形绘制，清晰美观

📦 文件结构

progressbar/
├── progressbar.cpp                # 组件实现
├── CMakeLists.txt                 # 构建配置
├── README.md                      # 本文档
└── assets/                        # 组件资源
    └── shaders/                   # 着色器源码
        ├── triangle.vert          # 顶点着色器（GLSL）
        ├── triangle.frag          # 片段着色器（GLSL）
        ├── compile_shaders.bat    # 着色器编译脚本
        └── spv/                   # 编译后的SPIR-V
            ├── triangle_vert.spv
            └── triangle_frag.spv

着色器说明:

  • ProgressBar 组件有自己的独立着色器
  • 使用基础渲染管线（顶点位置 + 顶点颜色）
  • Native 运行时自动根据组件名称从 assets/shaders/spv/ 加载
  • 进度条由矩形组成，使用相同的着色器渲染

🎨 视觉设计

进度条结构：
┌────────────────────────────────────────┐
│ ███████████████████░░░░░░░░░░░░░░░░░░ │  ← 前景（进度）
│                                        │
└────────────────────────────────────────┘
  ↑                                      ↑
  背景（灰色）                    边框

颜色方案

  • 背景: 深灰色 (RGB: 0.2, 0.2, 0.25)
  • 前景（进度）: 绿色 (RGB: 0.2, 0.7, 0.3)
  • 边框: 中灰色 (RGB: 0.4, 0.4, 0.45)
  • 文本: 白色 (RGB: 1.0, 1.0, 1.0)
  • 清屏: 深蓝灰 (RGB: 0.12, 0.12, 0.15)

🎮 交互方式

键盘操作

  • M 键: 切换控制模式
    • MANUAL（手动）
    • AUTO_LOOP（自动循环）
    • AUTO_ONCE（自动一次）
  • R 键: 重置进度到 0%
  • ESC 键: 退出组件
  • 左/右箭头: 手动控制进度（仅在 MANUAL 模式下）

控制模式

1. MANUAL 模式（手动控制）

  • 使用左右箭头键控制进度
  • 左箭头：每秒减少 50%
  • 右箭头：每秒增加 50%
  • 进度范围：0% - 100%

2. AUTO_LOOP 模式（自动循环）

  • 自动从 0% 增加到 100%
  • 到达 100% 后自动减少回 0%
  • 无限循环
  • 速度：每秒变化 30%

3. AUTO_ONCE 模式（自动一次）

  • 自动从当前进度增加到 100%
  • 到达 100% 后停止
  • 速度：每秒增加 30%

🏗️ 技术实现

核心数据结构

class ProgressBarComponent {
private:
    float progress;         // 当前进度 (0.0 - 1.0)
    float targetProgress;   // 目标进度
    float animationSpeed;   // 动画速度
    AnimationMode mode;     // 控制模式
    bool increasing;        // 方向（用于循环模式）
    
    // 进度条尺寸
    float barX, barY;       // 位置
    float barWidth;         // 宽度
    float barHeight;        // 高度
};

渲染流程

  1. 绘制边框 - drawRectangle() 绘制外边框
  2. 绘制背景 - drawRectangle() 绘制灰色背景
  3. 绘制进度 - drawRectangle() 绘制绿色前景
  4. 绘制文本 - drawText() 显示进度和说明

动画算法

// 平滑过渡算法
void onUpdate(float deltaTime) {
    if (progress < targetProgress) {
        progress += deltaTime * animationSpeed;
        if (progress > targetProgress) {
            progress = targetProgress;
        }
    } else if (progress > targetProgress) {
        progress -= deltaTime * animationSpeed;
        if (progress < targetProgress) {
            progress = targetProgress;
        }
    }
}

特点:

  • 线性插值
  • 防止超调
  • 双向支持（增加/减少）

🔧 构建和运行

构建组件

# 1. 进入组件目录
cd examples/cpp/progressbar

# 2. 创建构建目录
mkdir build
cd build

# 3. 配置 CMake
cmake .. -G "Visual Studio 17 2022" -A x64

# 4. 编译
cmake --build . --config Release

运行组件

# 复制 DLL 到 native/build/Release/
copy Release\progressbar.dll ..\..\..\native\build\Release\

# 运行组件
cd ..\..\..\native
.\build\Release\bitui_native.exe .\build\Release\progressbar.dll

输出:

[INFO] Component name: progressbar
[INFO] Shader path: ../examples/cpp/progressbar/assets/shaders/spv/
[INFO] Loading component: .\build\Release\progressbar.dll
[OK] Component loaded successfully
[OK] Component initialized
[INFO] Entering main loop...

📊 性能指标

  • 渲染图元: ~4 个矩形
  • 内存占用: < 500 字节
  • CPU 占用: 极低（仅动画计算）
  • 响应延迟: < 16ms (60 FPS)
  • 动画流畅度: 60 FPS 平滑过渡

🎓 学习要点

1. 进度条绘制

矩形分层:

// 边框（最底层）
drawRectangle(x - border, y - border, w + border*2, h + border*2, borderColor);

// 背景
drawRectangle(x, y, w, h, bgColor);

// 前景（进度）
float progressWidth = w * progress;
drawRectangle(x, y, progressWidth, h, fgColor);

2. 值的映射

进度百分比计算:

int percentage = (int)(progress * 100.0f);  // 0.0-1.0 → 0-100

尺寸映射:

float progressWidth = totalWidth * progress;  // 0.0-1.0 → 0-400 像素

3. 动画插值

线性插值（Lerp）:

current += (target - current) * speed * deltaTime;

优点:

  • 简单高效
  • 自然减速（越接近目标越慢）
  • 永远不会超调

4. 模式状态机

MANUAL ──M──> AUTO_LOOP ──M──> AUTO_ONCE ──M──> MANUAL
  ↑                                               │
  └───────────────────────────────────────────────┘

🐛 已知限制

  1. 文本渲染: 当前使用 drawText() 占位符
  2. 字体大小: 固定字体大小，不可调节
  3. 颜色自定义: 颜色硬编码，不支持运行时修改

📚 相关文档

🎉 下一步

学习完 ProgressBar 组件后，您可以:

  1. 实现 Button 组件: 添加点击交互
  2. 实现 Slider 组件: 学习拖动控制
  3. 优化 ProgressBar: 添加渐变色、圆角
  4. 组合控件: 创建包含多个进度条的面板

💡 扩展建议

渐变色进度条

// 根据进度改变颜色
float r = 1.0f - progress;  // 红色减少
float g = progress;         // 绿色增加
float color[4] = {r, g, 0.2f, 1.0f};

圆角进度条

// 使用 drawCircle 绘制圆角
float radius = barHeight / 2.0f;
drawCircle(barX, barY + radius, radius, color);  // 左端圆角
drawCircle(barX + barWidth, barY + radius, radius, color);  // 右端圆角
drawRectangle(barX, barY, barWidth, barHeight, color);  // 中间矩形

分段进度条

// 显示多个阶段
float segments[] = {0.25f, 0.5f, 0.75f, 1.0f};
for (int i = 0; i < 4; i++) {
    if (progress >= segments[i]) {
        drawRectangle(segmentX[i], y, segmentW, h, completedColor);
    }
}

组件状态: ✅ 已完成并测试通过
最后更新: 2025-10-12
维护者: Bit HCI Team