HTL.Aspose.MergeTemplate 1.0.1

Aspose.MergeTemplate

Thư viện trộn dữ liệu vào mẫu Excel có sẵn (lưu trên MinIO thông qua IStorageService) và xuất ra Excel/PDF bằng Aspose.

Đăng ký DI

services.AddAsposeMergeTemplate(configuration);

AppSettings ví dụ:

{
  "AsposeMergeTemplate": {
    "TemplateStorageType": 2,
    "OutputStorageType": 0,
    "TemplatePrefix": ""
  }
}

Cách dùng

var svc = serviceProvider.GetRequiredService<IMergeTemplateService>();

var result = await svc.MergeAsync(new MergeTemplateRequest
{
    AppCode = "System",
    CompanyCode = tenantCode,
    TemplateName = "mau-in/phieu-thu.xlsx",
    Data = mergeData, // MergeTemplateData (contracts thuần), không phụ thuộc HTL.Domain.Core
    ExportExcel = true,
    ExportPdf = true,

    // (Tuỳ chọn) custom xử lý cell cho riêng request này
    // CellValueHandle = new MyCustomCellValueHandle()
});

// result.OutputExcelPath / result.OutputPdfPath là tên file đã được lưu trên storage output (thường là Temp)

Hướng dẫn merge cột động (Dynamic Columns)

1) Quy ước trong file Excel template

• Ô neo (anchor cell): đặt 1 ô chứa placeholder theo dạng:
  • ##{tableName}.{key}##
  • Ví dụ: ##ChiTiet.SoLuong##
• Thư viện sẽ dùng ô neo này để xác định vị trí bắt đầu sinh cột động.
• Nếu template của bạn có header 2 tầng (group header):
  • Tầng group nằm ở hàng trên của ô neo (rowIndex - 1)
  • Tầng tên cột nằm ở đúng hàng của ô neo (rowIndex)
  • Dòng template để binding detail nằm ở hàng dưới (rowIndex + 1) và sẽ được set thành ##{tableName}.{FieldName}##

2) Khai báo rule sinh cột động (Metadata.DynamicColumnRules)

Bạn khai báo các rule để “bật” cột động tại các anchor key trong template:

mergeData.Metadata.DynamicColumnRules.Add(new MergeDynamicColumnRule
{
    Id = 1,
    TableName = "ChiTiet",
    Key = "SoLuong",       // khớp với ##ChiTiet.SoLuong##
    IsDynamic = true,
    ResultIndex = 0        // sẽ map với ColumnInfoDetails["ChiTiet"]["0"]
});

3) Truyền danh sách cột động thực tế (ColumnInfoDetails)

MergeTemplateData.ColumnInfoDetails có cấu trúc:

• tableName → resultIndex(string) → List<MergeColumnDynamicInfo>

Trong đó mỗi MergeColumnDynamicInfo mô tả 1 cột được sinh:

• GroupIndex: phải bằng DynamicColumnRule.Id để rule biết cột nào thuộc anchor nào
• Text: tiêu đề cột
• FieldName: tên field để sinh placeholder ở dòng template: ##{tableName}.{FieldName}##
• ParentName (tuỳ chọn): nếu có sẽ tạo group header và tự merge theo nhóm cùng ParentName
• Width: độ rộng cột
• DataType: kiểu dữ liệu để format mặc định

Ví dụ:

mergeData.ColumnInfoDetails["ChiTiet"] = new Dictionary<string, List<MergeColumnDynamicInfo>>
{
    ["0"] = new List<MergeColumnDynamicInfo>
    {
        new()
        {
            GroupIndex = 1,
            Text = "Kỳ 1",
            FieldName = "SoLuongKy1",
            ParentName = "Số lượng",
            Width = 12,
            DataType = MergeDataType.Decimal
        },
        new()
        {
            GroupIndex = 1,
            Text = "Kỳ 2",
            FieldName = "SoLuongKy2",
            ParentName = "Số lượng",
            Width = 12,
            DataType = MergeDataType.Decimal
        }
    }
};

4) Lưu ý quan trọng

• Nếu số cột động lớn hơn số cột đang merge trong template, thư viện sẽ Insert thêm cột và tự gán header/template.
• Nếu anchor cell đang merge, thư viện sẽ tự unmerge/merge lại để khớp số lượng cột động.
• Dữ liệu detail thật khi merge vẫn lấy theo Details[tableName] và placeholder ##{tableName}.{field}## ở dòng template.