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.