TJC.Cyclops.Reporting 2026.6.5.1

Cyclops.Reporting

Cyclops.Framework 框架中的报表生成组件，支持静态泛型报表和动态 SQL 报表两种模式。

功能特性

静态报表（原有功能）

基于泛型 List<T> 的报表导出，通过特性标注控制列信息：

• 支持 CSV 和 Excel（.xlsx/.xls）格式导出
• 使用 [ReportDescription] 特性自定义列标题、排序、格式
• 使用 [ReportIgnore] 特性忽略不需要导出的属性
• 支持 bool、DateTime、Enum 等类型的自动转换
• 支持自定义委托转换

动态报表（新增功能）

基于 Lua 脚本的动态 SQL 报表系统：

• Lua 脚本生成 SQL：支持动态条件拼接
• 列值转换：支持 None / ValueMap / LuaScript 三种转换类型
• 报表预览：支持前 N 行数据预览
• 报表导出：支持 CSV 和 Excel 格式
• 内置函数：HTTP、JSON、字符串、日期、加密、正则、日志等

技术栈

• .NET 8.0
• MoonSharp（Lua 脚本引擎）
• SqlSugar（通过 Cyclops.Orm）
• NPOI（Excel 处理）

安装

<PackageReference Include="TJC.Cyclops.Reporting" Version="2026.6.2.1" />

使用方式

静态报表

using Cyclops.Reporting;
using Cyclops.Reporting.Attrs;

// 定义数据模型
public class Hospital
{
    [ReportDescription("医院名称", 1)]
    public string Name { get; set; }

    [ReportDescription("是否重要", 2, "重要,不重要")]
    public bool IsImportant { get; set; }

    [ReportDescription("创建时间", 3, datetimeFormat: "yyyy-MM-dd")]
    public DateTime CreateTime { get; set; }

    [ReportIgnore]
    public string InternalField { get; set; }
}

// 使用
var data = new List<Hospital> { ... };
var report = new Report<Hospital>(data);

// 导出到文件
report.Export("医院信息.xlsx");
report.Export("医院信息.csv");

动态报表

1. 注册服务

using Cyclops.Reporting.Extensions;

builder.Services.AddCyclopsReporting();

2. 配置报表

报表配置存储在数据库中，包含两张表：

report_config（报表主配置）

report_column_config（列转换配置）

3. SQL 模板示例

SQL 模板使用 Lua 脚本，接收 params 参数，返回 SQL 字符串：

local sql = "SELECT u.user_name, u.create_time, d.dept_name FROM sys_user u LEFT JOIN sys_dept d ON u.dept_id = d.id WHERE 1=1"

if params.status then
    sql = sql .. " AND u.status = @status"
end

if params.startTime then
    sql = sql .. " AND u.create_time >= @startTime"
end

if params.keyword and params.keyword ~= "" then
    sql = sql .. " AND u.user_name LIKE @keyword"
end

return sql

4. 列转换 Lua 脚本示例

-- 定义转换函数
function GetUserName(userId)
    local resp = http_get("https://a.b.c/api/user/" .. userId)
    if resp then
        return resp
    end
    return ""
end

function GetStatusText(value)
    local map = {["1"]="启用", ["0"]="禁用"}
    return map[tostring(value)] or ""
end

5. 使用服务

using Cyclops.Reporting.Dynamic.Services;
using Cyclops.Reporting.Dynamic.Models;

public class ReportController
{
    private readonly DynamicReportService _reportService;
    private readonly ReportConfigService _configService;

    // 预览报表
    public async Task Preview()
    {
        var dt = await _reportService.PreviewAsync(
            reportConfigId: 1,
            sqlParams: new Dictionary<string, object>
            {
                { "status", 1 },
                { "startTime", DateTime.Now.AddDays(-30) }
            },
            previewRows: 50
        );
    }

    // 导出报表
    public async Task Export()
    {
        var stream = await _reportService.ExportAsync(
            reportConfigId: 1,
            sqlParams: new Dictionary<string, object>(),
            format: ExportFormat.Excel
        );

        // 保存到文件
        using var fs = new FileStream("报表.xlsx", FileMode.Create);
        await stream.CopyToAsync(fs);
    }

    // 保存报表配置
    public async Task SaveConfig()
    {
        var config = new DbReportConfig
        {
            Name = "用户报表",
            SqlTemplate = "local sql = 'SELECT ...' return sql",
            LuaScript = "function GetUserName(id) ... end",
            PreviewRows = 100,
            Status = 1
        };

        var id = await _configService.SaveConfigAsync(config);
    }

    // 保存列配置
    public async Task SaveColumns()
    {
        var columns = new List<DbReportColumnConfig>
        {
            new DbReportColumnConfig
            {
                ColumnName = "user_name",
                DisplayName = "用户名",
                SortNo = 1,
                ConverterType = "None"
            },
            new DbReportColumnConfig
            {
                ColumnName = "status",
                DisplayName = "状态",
                SortNo = 2,
                ConverterType = "ValueMap",
                ConverterConfig = "{\"1\":\"启用\",\"0\":\"禁用\"}"
            },
            new DbReportColumnConfig
            {
                ColumnName = "user_id",
                DisplayName = "用户姓名",
                SortNo = 3,
                ConverterType = "LuaScript",
                ConverterConfig = "GetUserName(value)"
            }
        };

        await _configService.SaveColumnConfigsAsync(1, columns);
    }
}

Lua 引擎内置函数

项目结构

Cyclops.Reporting/
├── Core/                              # 静态报表
│   ├── ReportBase.cs                  # 基类
│   ├── ReportColumn.cs                # 列信息
│   ├── ReportCsv.cs                   # CSV 导出
│   └── ReportExcel.cs                 # Excel 导出
├── Dynamic/                           # 动态报表
│   ├── Entities/
│   │   ├── DbReportConfig.cs          # 报表配置实体
│   │   └── DbReportColumnConfig.cs    # 列配置实体
│   ├── Models/
│   │   ├── EnumConverterType.cs       # 转换类型枚举
│   │   ├── ExportFormat.cs            # 导出格式枚举
│   │   ├── ReportPreviewInput.cs      # 预览请求模型
│   │   ├── ReportExportInput.cs       # 导出请求模型
│   │   └── DynamicReportResult.cs     # 报表结果模型
│   ├── Services/
│   │   ├── LuaScriptEngine.cs         # Lua 脚本引擎
│   │   ├── DynamicReportService.cs    # 动态报表服务
│   │   └── ReportConfigService.cs     # 配置管理服务
│   └── Repository/
│       └── DynamicReportRepository.cs # 数据访问层
├── Attrs/
│   ├── ReportDescriptionAttribute.cs  # 列描述特性
│   └── ReportIgnoreAttribute.cs       # 忽略特性
├── Extensions/
│   └── ServiceCollectionExtensions.cs # DI 扩展
└── Report.cs                          # 静态报表入口

依赖

• Cyclops.Common
• Cyclops.Orm
• MoonSharp

许可证

保留所有权利