TJC.Cyclops.Reporting 2026.5.7.2

📊 Cyclops.Reporting

📝 项目概述

Cyclops.Reporting 是 Cyclops.Framework 框架中的报表生成专家，为您的应用程序提供强大、灵活的报表设计、生成和导出功能！ 🚀

我们精心设计的组件支持多种报表格式（如PDF、Excel、Word、CSV等），并提供报表模板管理、数据源配置、图表生成等功能，适用于企业级应用中的各类数据展示和分析场景。无论是简单的销售报表，还是复杂的财务分析，Cyclops.Reporting都能为您提供出色的支持。

✨ 为什么选择 Cyclops.Reporting？

• 多格式支持：支持PDF、Excel、Word、CSV、HTML等多种报表格式
• 强大的模板系统：灵活的报表模板设计和管理
• 丰富的数据源：支持SQL、对象等多种数据源
• 图表功能：内置各类图表生成能力
• 易于集成：与.NET依赖注入系统无缝集成
• 高性能：优化的报表生成和导出性能

🎯 核心功能模块

🚀 报表引擎

• 多格式支持：生成PDF、Excel、Word、CSV、HTML等多种格式报表
• 布局控制：精细的报表渲染与布局控制
• 分页设置：灵活的报表分页与页眉页脚设置
• 条件样式：支持条件样式与表达式，增强报表表现力

📋 模板管理

• 模板编辑：报表模板创建与编辑
• 版本控制：模板版本管理，确保模板更新的可追溯性
• 缓存机制：模板缓存，提高报表生成速度
• 参数配置：灵活的模板参数配置，适应不同场景

📊 数据源集成

• SQL数据源：支持SQL查询作为数据源
• 对象数据源：支持.NET对象作为数据源
• 多源合并：支持多个数据源的合并使用
• 数据处理：内置数据过滤与排序功能

📈 图表生成

• 丰富图表：支持柱状图、折线图、饼图等多种图表类型
• 样式自定义：灵活的图表样式自定义
• 动态绑定：图表数据的动态绑定
• 交互功能：HTML格式报表支持交互式图表

📤 报表导出

• 多格式导出：支持多种格式的报表导出
• 选项配置：导出选项的详细配置
• 批量导出：批量生成和导出多个报表
• 流式优化：流式导出，优化内存使用

⚡ 高级功能

• 分组汇总：报表数据的分组与汇总
• 交叉表：支持复杂的交叉表报表
• 子报表：支持子报表功能，增强报表复杂度
• 安全性：报表安全性控制，保护敏感数据

🛠️ 技术栈

• .NET 8.0：基础开发框架，利用最新的.NET特性
• ClosedXML：强大的Excel文件处理库
• iTextSharp：专业的PDF生成库
• Cyclops.Common：框架核心公共组件
• Cyclops.Data：数据处理库

📦 环境依赖

• .NET 8.0 SDK 或更高版本
• 可选：数据库连接：用于SQL数据源
• 支持的平台：Windows、Linux、macOS
• IDE推荐：Visual Studio 2022、Visual Studio Code

🚀 安装配置

🔍 安装方式

NuGet包管理器

Install-Package Cyclops.Reporting

.NET CLI

dotnet add package Cyclops.Reporting

PackageReference

<PackageReference Include="Cyclops.Reporting" Version="1.0.0" />

⚙️ 基本配置

在应用程序启动时进行配置，享受开箱即用的报表生成能力！

// 在Program.cs或Startup.cs中
using Cyclops.Reporting;

var builder = WebApplication.CreateBuilder(args);

// 添加Cyclops.Reporting服务
builder.Services.AddCyclopsReporting(options => {
    // 报表模板路径
    options.TemplatePath = Path.Combine(AppContext.BaseDirectory, "ReportTemplates");
    
    // 临时文件路径
    options.TempFilePath = Path.Combine(AppContext.BaseDirectory, "Temp");
    
    // 缓存配置
    options.EnableTemplateCache = true;           // 启用模板缓存
    options.CacheExpiration = TimeSpan.FromHours(1); // 缓存过期时间
    
    // 导出配置
    options.DefaultExportFormat = ExportFormat.PDF;  // 默认导出格式
    options.MaxReportRecords = 100000;             // 最大记录数
    
    // 启用日志
    options.EnableLogging = true;                  // 启用日志记录
});

// ...

🎯 配置建议

• 模板路径：确保模板路径存在且有适当的访问权限
• 临时文件：确保临时文件路径有足够的存储空间
• 缓存设置：根据系统内存和模板数量调整缓存设置
• 最大记录数：根据系统性能和内存情况设置合理的最大记录数
• 日志记录：在开发和测试环境建议启用日志，生产环境根据需要调整

📝 代码示例

📄 基本报表生成示例

以下示例展示了如何使用 Cyclops.Reporting 生成基本报表：

using Cyclops.Reporting.Models;
using Cyclops.Reporting.Services;
using Microsoft.Extensions.DependencyInjection;

// 获取报表服务
var reportService = serviceProvider.GetRequiredService<IReportService>();

// 准备报表数据
var reportData = new Dictionary<string, object>
{
    { "Title", "月度销售报表" },
    { "Month", "2024年6月" },
    { "CompanyName", "示例公司" },
    { "SalesData", new List<SalesRecord> {
        new SalesRecord { Product = "产品A", Quantity = 100, Amount = 15000 },
        new SalesRecord { Product = "产品B", Quantity = 150, Amount = 22500 },
        new SalesRecord { Product = "产品C", Quantity = 80, Amount = 12000 }
    }}
};

// 生成报表
var reportResult = await reportService.GenerateReportAsync(
    templateName: "MonthlySalesReport",
    data: reportData,
    format: ExportFormat.PDF
);

// 保存报表到文件
await using (var fileStream = new FileStream("SalesReport.pdf", FileMode.Create))
{
    await reportResult.Content.CopyToAsync(fileStream);
}

Console.WriteLine($"报表已生成: {reportResult.FileName}");
Console.WriteLine($"文件大小: {reportResult.Content.Length} 字节");

📊 动态SQL报表示例

以下示例展示了如何使用 Cyclops.Reporting 生成基于SQL查询的报表：

using Cyclops.Reporting.Models;
using Cyclops.Reporting.Services;
using Microsoft.Extensions.DependencyInjection;

// 获取报表服务
var reportService = serviceProvider.GetRequiredService<IReportService>();

// 配置SQL数据源
var sqlDataSource = new SqlDataSourceConfig
{
    ConnectionString = "Your_Connection_String",
    Query = "SELECT p.ProductName, SUM(o.Quantity) as TotalQuantity, SUM(o.Quantity * p.Price) as TotalAmount " +
            "FROM Orders o JOIN Products p ON o.ProductId = p.Id " +
            "WHERE o.OrderDate BETWEEN @StartDate AND @EndDate " +
            "GROUP BY p.ProductName"
};

// 设置查询参数
var parameters = new Dictionary<string, object>
{
    { "StartDate", new DateTime(2024, 1, 1) },
    { "EndDate", new DateTime(2024, 12, 31) }
};

// 生成基于SQL的报表
var sqlReportResult = await reportService.GenerateReportFromSqlAsync(
    templateName: "SalesAnalysisReport",
    dataSource: sqlDataSource,
    parameters: parameters,
    format: ExportFormat.Excel
);

// 保存报表
await using (var fileStream = new FileStream("SalesAnalysis.xlsx", FileMode.Create))
{
    await sqlReportResult.Content.CopyToAsync(fileStream);
}

📈 图表报表示例

以下示例展示了如何使用 Cyclops.Reporting 生成包含图表的报表：

using Cyclops.Reporting.Models;
using Cyclops.Reporting.Services;
using Microsoft.Extensions.DependencyInjection;

// 获取报表服务
var reportService = serviceProvider.GetRequiredService<IReportService>();

// 准备图表数据
var chartData = new ChartData
{
    Title = "季度销售趋势",
    ChartType = ChartType.Line,
    XAxisTitle = "季度",
    YAxisTitle = "销售额（万元）",
    Series = new List<ChartSeries>
    {
        new ChartSeries
        {
            Name = "2023年",
            Data = new List<double> { 120, 180, 150, 210 }
        },
        new ChartSeries
        {
            Name = "2024年",
            Data = new List<double> { 150, 220, 190, 260 }
        }
    },
    Categories = new List<string> { "Q1", "Q2", "Q3", "Q4" }
};

// 生成包含图表的报表
var chartReportData = new Dictionary<string, object>
{
    { "ReportTitle", "销售趋势分析报告" },
    { "ReportDate", DateTime.Now.ToString("yyyy-MM-dd") },
    { "ChartData", chartData },
    { "AnalysisNotes", "2024年销售额整体呈上升趋势，Q2增长最为明显" }
};

var chartReportResult = await reportService.GenerateReportAsync(
    templateName: "ChartReport",
    data: chartReportData,
    format: ExportFormat.PDF
);

// 保存图表报表
await using (var fileStream = new FileStream("ChartReport.pdf", FileMode.Create))
{
    await chartReportResult.Content.CopyToAsync(fileStream);
}

📦 批量报表生成示例

以下示例展示了如何使用 Cyclops.Reporting 批量生成多个报表：

using Cyclops.Reporting.Models;
using Cyclops.Reporting.Services;
using Microsoft.Extensions.DependencyInjection;

// 获取报表服务
var reportService = serviceProvider.GetRequiredService<IReportService>();

// 准备多个报表的生成请求
var reportRequests = new List<ReportRequest>
{
    new ReportRequest
    {
        TemplateName = "ProductInventoryReport",
        Data = new Dictionary<string, object> {
            { "WarehouseId", 1 },
            { "AsOfDate", DateTime.Now }
        },
        Format = ExportFormat.Excel,
        FileName = "Warehouse1_Inventory.xlsx"
    },
    new ReportRequest
    {
        TemplateName = "ProductInventoryReport",
        Data = new Dictionary<string, object> {
            { "WarehouseId", 2 },
            { "AsOfDate", DateTime.Now }
        },
        Format = ExportFormat.Excel,
        FileName = "Warehouse2_Inventory.xlsx"
    },
    new ReportRequest
    {
        TemplateName = "SalesSummaryReport",
        Data = new Dictionary<string, object> {
            { "Period", "Monthly" },
            { "Year", 2024 },
            { "Month", 6 }
        },
        Format = ExportFormat.PDF,
        FileName = "June_Sales_Summary.pdf"
    }
};

// 批量生成报表
var batchResults = await reportService.GenerateBatchReportsAsync(reportRequests);

// 保存所有生成的报表
foreach (var result in batchResults)
{
    await using (var fileStream = new FileStream(result.FileName, FileMode.Create))
    {
        await result.Content.CopyToAsync(fileStream);
    }
    Console.WriteLine($"已生成: {result.FileName}");
}

// 也可以将所有报表打包成ZIP文件
var zipStream = await reportService.PackageReportsToZipAsync(batchResults);
await using (var zipFileStream = new FileStream("AllReports.zip", FileMode.Create))
{
    await zipStream.CopyToAsync(zipFileStream);
}

Console.WriteLine("所有报表已打包到 AllReports.zip");

📋 自定义报表模板管理示例

以下示例展示了如何使用 Cyclops.Reporting 管理报表模板：

using Cyclops.Reporting.Services;
using Microsoft.Extensions.DependencyInjection;

// 获取报表模板服务
var templateService = serviceProvider.GetRequiredService<IReportTemplateService>();

// 上传新模板
await using (var templateStream = File.OpenRead("NewReportTemplate.xlsx"))
{
    var templateInfo = await templateService.UploadTemplateAsync(
        name: "CustomReportTemplate",
        description: "自定义业务报表模板",
        content: templateStream,
        format: TemplateFormat.Excel
    );
    
    Console.WriteLine($"模板已上传: {templateInfo.Name}, ID: {templateInfo.Id}");
}

// 获取所有可用模板
var templates = await templateService.GetAllTemplatesAsync();
Console.WriteLine("可用的报表模板:");
foreach (var template in templates)
{
    Console.WriteLine($"- {template.Name} ({template.Format}) - {template.Description}");
}

// 更新模板
await using (var updatedStream = File.OpenRead("UpdatedTemplate.xlsx"))
{
    await templateService.UpdateTemplateAsync(
        id: "template_id",
        name: "UpdatedCustomTemplate",
        description: "已更新的自定义模板",
        content: updatedStream
    );
}

// 删除模板
await templateService.DeleteTemplateAsync("template_id");
Console.WriteLine("模板已删除");

## 🤝 贡献者

我们欢迎社区贡献！如果您有任何改进建议或功能需求，欢迎提交PR或Issue。

- **yswenli**：核心开发者

## 📋 版本信息
- **当前版本**：[![NuGet version (Cyclops.Framework)](https://img.shields.io/nuget/v/Cyclops.Framework.svg?style=flat-square)](https://www.nuget.org/packages?q=TJC.Cyclops)
- **作者**：yswenli
- **描述**：企服版框架中报表生成组件
- **更新频率**：定期更新，持续改进

## 📄 许可证

保留所有权利

## 🎉 结语

Cyclops.Reporting 致力于为您的应用程序提供强大、灵活的报表生成能力。我们相信，通过简化报表生成的复杂性，您可以更专注于业务逻辑的实现，构建出更具洞察力的数据分析和展示应用。

如果您有任何问题或建议，欢迎与我们联系！让我们一起构建更好的报表解决方案！ 🚀