【WinForm UI控件系列】旋转进度条、等待进度条、StatusForm、WaitingForm进度条、蒙版等待

基于 Layered Window 技术实现的高性能加载动画控件，支持多种动画类型、半透明遮罩、SVG图标、五种类型等功能

功能特性

• ✅ 多种动画类型：圆点旋转、圆弧旋转、圆环填充、进度条、滑块
• ✅ 半透明遮罩：真正的透明效果，使用 Layered Window 技术
• ✅ SVG 图标支持：可替换动画为自定义 SVG 图标
• ✅ 点击关闭：支持点击遮罩层或控件本身关闭
• ✅ 跟随窗体：自动跟随父窗体移动
• ✅ 鼠标穿透控制：可选择是否阻止鼠标事件穿透到下层
• ✅ 高性能渲染：GDI+ 双缓冲，流畅无闪烁
• ✅ StatusForm：进度条模式，从0%-100%显示，可更新进度值
• ✅ WaitingForm：滑块模式，滑块左右来回晃动
• ✅ 窗口透明度：支持设置窗口整体透明度

一、效果

二、说明文档

快速开始

基本用法

using AntdUIEx.Controls;
using AntdUIEx.Enum;

// 创建实例
var spin = new SpinEx();
spin.Text = "正在加载...";
spin.SpinSize = SpinSize.Medium;

// 显示加载（覆盖整个窗体）
spin.Show(this);

// 关闭加载
spin.Close();

显示在指定控件区域

// 显示在 GroupBox 内
spin.Show(groupBox1);

// 在中央显示（无遮罩模式）
spin.ShowCenter(panel1);

进度条模式（StatusForm）

// 显示进度条提示框
spin.ShowStatus(this, "数据加载中(47%)......", 3);

// 更新进度
spin.UpdateProgress(50);  // 更新到50%
spin.UpdateProgress(100); // 更新到100%，自动关闭

滑块模式（WaitingForm）

// 显示滑块等待提示框
spin.ShowWaiting(this, "系统正在处理中，请稍候...", 2);

属性详解

外观属性

属性名	类型	默认值	说明
Text	string	"加载中..."	加载提示文本
SpinSize	SpinSize	Medium	控件大小（Small/Medium/Large）
SpinType	SpinType	Dots	动画类型（Dots/Arc/FilledDots/Progress/Slider）
FillColor	Color	AntDesignColors.Primary	动画颜色
ForeColor	Color	Color.Black	文本颜色
WindowOpacity	float	1.0f	窗口透明度（0-1），1表示完全不透明

遮罩属性

属性名	类型	默认值	说明
Mask	bool	true	是否启用遮罩层
MaskColor	Color	Color.FromArgb(128, 0, 0, 0)	遮罩颜色（含透明度）
MaskClickToClose	bool	false	点击是否关闭
BlockMouse	bool	true	是否阻止鼠标穿透

动画属性

属性名	类型	默认值	说明
AnimationInterval	int	50	动画间隔（毫秒），越大越慢
IsRunning	bool	true	动画是否运行

SVG 图标属性

属性名	类型	默认值	说明
ShowIcon	bool	false	是否显示 SVG 图标替代动画
IconSvg	string	null	SVG 图标名称（如 "apple"）

进度条属性

属性名	类型	默认值	说明
ProgressValue	int	0	当前进度值（0-100）
ShowProgressLabel	bool	true	是否显示进度百分比标签

动画类型说明

Dots（圆点旋转）

4 个圆点围绕中心旋转，透明度渐变。

spin.SpinType = SpinType.Dots;

Arc（圆弧旋转）

两个半圆弧交替旋转，带圆角端点。

spin.SpinType = SpinType.Arc;

FilledDots（圆环填充）

灰色圆环底色，填充色从 0% 渐变到 100%。

spin.SpinType = SpinType.FilledDots;

Progress（进度条模式）

显示进度条提示框，带标题栏和进度条。

spin.SpinType = SpinType.Progress;

Slider（滑块模式）

显示滑块等待提示框，滑块在轨道内左右来回晃动。

spin.SpinType = SpinType.Slider;

方法详解

ShowStatus 方法

显示进度条提示框。

// 使用默认标题"提示"
void ShowStatus(Control parent, string text, int autoCloseDelay = 0);

// 使用自定义标题
void ShowStatus(Control parent, string title, string text, int autoCloseDelay = 0);

参数说明：

• parent：父控件，提示框居中显示在其上方
• title：标题栏文本（可选，默认为"提示"）
• text：提示消息内容
• autoCloseDelay：自动关闭延时（秒），0表示不自动关闭

ShowWaiting 方法

显示滑块等待提示框。

// 使用默认标题"提示"
void ShowWaiting(Control parent, string text, int autoCloseDelay = 0);

// 使用自定义标题
void ShowWaiting(Control parent, string title, string text, int autoCloseDelay = 0);

参数说明：

• parent：父控件，提示框居中显示在其上方
• title：标题栏文本（可选，默认为"提示"）
• text：提示消息内容
• autoCloseDelay：自动关闭延时（秒），0表示不自动关闭

UpdateProgress 方法

更新进度值。

void UpdateProgress(int value);

参数说明：

• value：进度值（0-100），达到100时自动关闭

使用示例

示例 1：基础遮罩加载

private SpinEx? spin;

private void btn_Load_Click(object sender, EventArgs e)
{
    spin = new SpinEx();
    spin.Text = "数据加载中...";
    spin.SpinSize = SpinSize.Large;
    spin.MaskColor = Color.FromArgb(100, 0, 0, 0);  // 半透明黑色
    spin.MaskClickToClose = true;  // 点击关闭
    spin.Show(this);
}

private void btn_Stop_Click(object sender, EventArgs e)
{
    spin?.Close();
}

示例 2：局部区域加载

// 仅在 Panel 内显示加载动画
spin.Show(panelData);

示例 3：使用 SVG 图标

spin.ShowIcon = true;
spin.IconSvg = "apple";  // 使用内置 apple 图标
spin.Text = "处理中...";
spin.Show(this);

示例 4：进度条模式

var spin = new SpinEx();
spin.ShowStatus(this, "加载", "数据加载中(11%)......", 5);

// 在后台任务中更新进度
for (int i = 0; i <= 100; i += 10)
{
    Thread.Sleep(500);
    spin.UpdateProgress(i);
}

示例 5：滑块等待模式

var spin = new SpinEx();
spin.ShowWaiting(this, "处理", "系统正在处理中，请稍候...", 3);

示例 6：设置窗口透明度

spin.WindowOpacity = 0.95f;  // 95%不透明
spin.Show(this);

完整示例代码

public partial class MainForm : Form
{
    private SpinEx? spin;

    private async void btn_Download_Click(object sender, EventArgs e)
    {
        try
        {
            // 显示进度条
            spin = new SpinEx();
            spin.ShowStatus(this, "下载", "正在下载数据...", 0);

            // 模拟下载进度
            for (int i = 0; i <= 100; i += 5)
            {
                await Task.Delay(200);
                spin.UpdateProgress(i);
            }

            MessageBoxEx.ShowSuccess(this, "下载完成！");
        }
        catch (Exception ex)
        {
            MessageBoxEx.ShowError(this, $"下载失败：{ex.Message}");
        }
        finally
        {
            spin?.Close();
        }
    }
}

注意事项

1. 线程安全 ：Show 和 Close 方法必须在 UI 线程调用
2. 资源释放 ：使用完毕后调用 Close() 释放资源
3. 父窗体：控件会自动跟随父窗体移动
4. Layered Window：使用 Windows 分层窗口技术实现透明效果
5. StatusForm/WaitingForm：这两种模式会自动启用遮罩并显示带标题栏的提示框

常见问题

Q: 遮罩层不透明？

A: 检查 MaskColor 的 Alpha 值，范围是 0-255，值越小越透明。

Q: 点击无法关闭？

A: 确保设置了 MaskClickToClose = true，且 BlockMouse 不为 true 时会阻止穿透。

Q: SVG 图标不显示？

A: 确认图标名称存在于 SvgIconManager 中，使用 ShowIcon = true 启用图标模式。

Q: 动画不流畅？

A: 尝试调整 AnimationInterval，或减小窗口大小以提高性能。

Q: ShowStatus 不自动消失？

A: 确保在调用 ShowStatus 时设置了 autoCloseDelay 参数，或通过 UpdateProgress(100) 触发关闭。

相关枚举

public enum SpinSize
{
    Small,   // 24px
    Medium,  // 32px
    Large    // 48px
}

public enum SpinType
{
    Dots,       // 圆点旋转
    Arc,        // 圆弧旋转
    FilledDots, // 圆环填充
    Progress,   // 进度条模式
    Slider      // 滑块模式
}

更新日志

2026-05-15

• 新增 Progress（进度条）模式
• 新增 Slider（滑块）模式
• 新增 ShowStatus 方法，显示进度条提示框
• 新增 ShowWaiting 方法，显示滑块等待提示框
• 新增 UpdateProgress 方法，更新进度值
• 新增 WindowOpacity 属性，设置窗口透明度
• 添加带标题的方法重载
• 优化提示框界面样式（圆角、边框、标题栏）

2026-04-17

• 初始版本发布
• 支持三种动画类型
• 支持 SVG 图标旋转
• 支持半透明遮罩

三、后记

更多功能和控件完善中，持续关注，如有需求或好的建议，请留言(xue5zhijing)