ClosedXML主明细报表生成异常：无法填充Orders与Items层级数据

一、确认数据结构的正确性 #

ClosedXML报表引擎要求子层级必须是父对象的集合类型属性，先检查你的数据类是否符合以下结构：

public class Item
{
    public string ItemCode { get; set; }
    public string ItemName { get; set; }
    public decimal Quantity { get; set; }
    public decimal UnitPrice { get; set; }
}

public class Order
{
    public string OrderNo { get; set; }
    public DateTime OrderDate { get; set; }
    public List<Item> Items { get; set; } = new List<Item>();
}

public class Customer
{
    public string CustNo { get; set; }
    public string Company { get; set; }
    public List<Order> Orders { get; set; } = new List<Order>();
}

二、Excel模板的正确配置（核心步骤） #

之前的{{items.Orders.OrderNo}}写法是错误的，ClosedXML嵌套明细不需要前缀，只需按范围命名规则设置：

1. 客户主范围：选中包含CustNo、Company字段的整行，在Excel名称框输入Customers回车。
2. 订单明细范围：选中订单字段（如OrderNo、OrderDate）所在整行，命名为Customers_Orders（规则：主范围名 + 下划线 + 子集合属性名）。
3. 商品明细范围：选中商品字段（如ItemCode、ItemName）所在整行，命名为Customers_Orders_Items（规则：上一级明细范围名 + 下划线 + 子集合属性名）。

模板占位符直接写属性名：

• 客户行：{{CustNo}}、{{Company}}
• 订单行：{{OrderNo}}、{{OrderDate}}
• 商品行：{{ItemCode}}、{{ItemName}}

三、C#代码实现示例 #

using ClosedXML.Excel;
using ClosedXML.Report;
using System.Collections.Generic;
using System.IO;

// 1. 构造测试数据
var testData = new List<Customer>
{
    new Customer
    {
        CustNo = "C001",
        Company = "ABC Corp",
        Orders = new List<Order>
        {
            new Order
            {
                OrderNo = "O001",
                OrderDate = new DateTime(2024, 5, 1),
                Items = new List<Item>
                {
                    new Item { ItemCode = "I001", ItemName = "Laptop", Quantity = 1, UnitPrice = 899.99m },
                    new Item { ItemCode = "I002", ItemName = "Mouse", Quantity = 2, UnitPrice = 29.99m }
                }
            },
            new Order
            {
                OrderNo = "O002",
                OrderDate = new DateTime(2024, 5, 5),
                Items = new List<Item>
                {
                    new Item { ItemCode = "I003", ItemName = "Keyboard", Quantity = 1, UnitPrice = 49.99m }
                }
            }
        }
    },
    new Customer
    {
        CustNo = "C002",
        Company = "XYZ Ltd",
        Orders = new List<Order>
        {
            new Order
            {
                OrderNo = "O003",
                OrderDate = new DateTime(2024, 5, 10),
                Items = new List<Item>
                {
                    new Item { ItemCode = "I004", ItemName = "Monitor", Quantity = 1, UnitPrice = 299.99m }
                }
            }
        }
    }
};

// 2. 加载模板并填充数据
var templatePath = @"C:\Templates\CustomerReportTemplate.xlsx";
var outputPath = @"C:\Reports\CustomerReport_Output.xlsx";

using (var template = new XLTemplate(templatePath))
{
    template.AddVariable("Customers", testData);
    template.Generate();
    template.SaveAs(outputPath);
}

四、官方示例的标准数据结构 #

ClosedXML官方示例中三级报表的数据结构和上述示例完全一致，核心是父对象包含子集合属性，报表引擎会自动遍历每一层集合并填充对应行。

内容的提问来源于stack exchange，提问作者Ing. Marquez Adam