XyProgressDialog 1.3.0

XyProgressDialog

一个现代化的 WPF 进度对话框组件，支持滚动动画和 Fluent Design 风格。

✨ 特性

• 🎨 Fluent Design 风格 - 完美符合 Windows 11 设计语言
• 🔄 智能滚动动画 - 进度不确定时自动显示滚动动画
• 📊 确定进度显示 - 支持精确的百分比进度
• ❌ 取消操作 - 支持用户取消长时间任务
• 🎯 非阻塞 - 不阻塞 UI 线程
• 🔧 易于使用 - 简单的 API，开箱即用

📦 安装

通过 NuGet 包管理器

Install-Package XyProgressDialog

通过 .NET CLI

dotnet add package XyProgressDialog

通过 PackageReference

<PackageReference Include="XyProgressDialog" Version="1.0.0" />

🚀 快速开始

基本使用

using XyProgressDialog.ViewModels;

// 显示进度对话框并执行任务
ProgressExecutor.Execute("处理文件", reporter =>
{
    for (int i = 0; i <= 100; i++)
    {
        // 报告进度（0-1 之间的值）
        reporter.Report(i / 100.0);
        
        // 执行实际工作
        Thread.Sleep(50);
        
        // 检查是否被取消
        if (reporter.IsCancelled)
            break;
    }
});

效果演示

滚动动画模式（进度不确定）：

┌─────────────────────────────────┐
│ 连接服务器                      │
│ 处理中...                       │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ [▮▮▮▮ → → → →]                 │  ← 循环滚动
└─────────────────────────────────┘

确定进度模式：

┌─────────────────────────────────┐
│ 处理文件                        │
│ 处理中...                       │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ [■■■■■■■■░░░░░░░░░░]      45.5%│  ← 精确百分比
└─────────────────────────────────┘

📖 使用示例

示例 1：文件下载（确定进度）

ProgressExecutor.Execute("下载文件", reporter =>
{
    var totalBytes = 1000000;
    var downloadedBytes = 0;
    
    while (downloadedBytes < totalBytes)
    {
        // 模拟下载
        var chunk = Math.Min(10000, totalBytes - downloadedBytes);
        downloadedBytes += chunk;
        Thread.Sleep(50);
        
        // 报告进度
        reporter.Report((double)downloadedBytes / totalBytes);
        
        if (reporter.IsCancelled)
            break;
    }
});

示例 2：网络连接（不确定进度 → 确定进度）

ProgressExecutor.Execute("初始化", reporter =>
{
    // 第一阶段：连接（显示滚动动画）
    reporter.Report(0);
    ConnectToServer();
    
    // 第二阶段：加载数据（显示具体进度）
    var items = GetItemList();
    for (int i = 0; i < items.Count; i++)
    {
        ProcessItem(items[i]);
        reporter.Report((i + 1) / (double)items.Count);
        
        if (reporter.IsCancelled)
            break;
    }
});

示例 3：自定义选项

ProgressExecutor.Execute(
    title: "批量处理",
    action: reporter =>
    {
        // 你的处理逻辑
        for (int i = 0; i <= 100; i++)
        {
            reporter.Report(i / 100.0);
            Thread.Sleep(50);
        }
    },
    canCancel: true,        // 是否允许取消（默认 true）
    autoClose: true,        // 完成后自动关闭（默认 true）
    autoCloseDelay: 500     // 自动关闭延迟毫秒数（默认 500）
);

示例 4：处理异常

try
{
    ProgressExecutor.Execute("处理数据", reporter =>
    {
        for (int i = 0; i <= 100; i++)
        {
            if (reporter.IsCancelled)
                throw new OperationCanceledException("用户取消操作");
            
            reporter.Report(i / 100.0);
            ProcessData(i);
        }
    });
}
catch (OperationCanceledException)
{
    MessageBox.Show("操作已取消");
}
catch (Exception ex)
{
    MessageBox.Show($"处理失败：{ex.Message}");
}

🎨 设计特点

Fluent Design 风格

• 符合 Windows 11 设计规范
• 柔和的圆角和阴影
• 流畅的交互动画
• 统一的颜色系统

智能进度显示

• 进度 = 0：自动显示滚动动画
• 进度 > 0：显示具体百分比
• 进度 = 100%：显示完成状态

用户体验优化

• 非模态窗口，不阻塞主界面
• 支持取消操作
• 自动关闭（可配置）
• 清晰的状态提示

🔧 API 文档

ProgressExecutor.Execute

public static void Execute(
    string title,                    // 窗口标题
    Action<ProgressReporter> action, // 要执行的任务
    bool canCancel = true,           // 是否允许取消
    bool autoClose = true,           // 完成后是否自动关闭
    int autoCloseDelay = 500         // 自动关闭延迟（毫秒）
)

ProgressReporter

public class ProgressReporter
{
    // 报告进度（0-1 之间的值）
    public void Report(double progress);
    
    // 检查是否被取消
    public bool IsCancelled { get; }
}

⚙️ 系统要求

• .NET 8.0 或更高版本
• Windows 平台
• WPF 应用程序

📦 依赖项

• CommunityToolkit.Mvvm (>= 8.2.2)
• PropertyChanged.Fody (>= 4.1.0)

📄 许可证

本项目采用 MIT 许可证。

🤝 贡献

欢迎贡献！请随时提交 Pull Request 或创建 Issue。

🔗 相关链接

• NuGet 包
• GitHub 仓库
• 问题反馈