Xuất Word/PDF với Aspose

govex-cloud-aspose xuất tài liệu Word từ template có MERGEFIELD: nhận Map dữ liệu, thực hiện mail merge và trả về file DOCX/PDF/HTML/DOC. Dùng khi service cần sinh văn bản từ biểu mẫu sẵn có hoặc từ file người dùng tải lên.

Khi nào sử dụng

• Sinh văn bản từ template Word theo templateCode nằm trong thư mục template đã cấu hình.
• Sinh văn bản từ template do người dùng upload (truyền InputStream).
• Khóa merge field trên file DOCX đầu ra để người dùng chỉnh sửa được nội dung thường nhưng không sửa được dữ liệu hệ thống đã merge.
• Tải ảnh trong template theo URL thông qua FileDownloader.
• Khai báo bảng dữ liệu cho Aspose.Cells bằng annotation @DataTable.

Cài đặt

Thêm dependency vào service; version do BOM quản lý, không khai trong pom.xml:

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-aspose</artifactId>
</dependency>

Xem hướng dẫn BOM/parent tại Cài đặt.

Cấu hình

Property	Mô tả	Mặc định
govex.aspose.template	Thư mục chứa template Word. Nếu bắt đầu bằng classpath: thì tra theo classpath, ngược lại tra theo filesystem; tên file template chính là templateCode truyền vào	classpath:templates

Ví dụ trỏ template ra thư mục ngoài classpath:

govex:
  aspose:
    template: file:/opt/govex/templates

Sử dụng

DocExporter là bean mặc định do auto-configuration đăng ký; inject trực tiếp vào service:

@Service
@RequiredArgsConstructor
public class VanBanService {

    private final DocExporter docExporter;

    public ExportData xuatPdf(String templateCode, Map<String, Object> duLieu) {
        return docExporter.export(ExportType.PDF, templateCode, duLieu);
    }

    public ExportData xuatDocxKhoaField(String fileName, InputStream template,
                                        Map<String, Object> duLieu) {
        DocExportOptions options = DocExportOptions.lockMergeFields(Set.of("maHoSo", "ngayBanHanh"));
        return docExporter.export(ExportType.DOCX, fileName, template, duLieu, options);
    }
}

Kết quả trả về là record ExportData(fileName, data, etag), trong đó data() là Object (thực tế chứa byte[]) và etag() là MD5 của file — dùng để ghi response tải file.

Muốn template tải được ảnh theo URL, khai báo thêm bean FileDownloader:

@Bean
FileDownloader fileDownloader(RestTemplate restTemplate) {
    return url -> restTemplate.getForObject(url, byte[].class);
}

Template có thể dùng marker {{field}}, [[field]], «field» — dependency chuẩn hóa thành MERGEFIELD trước khi merge. Giá trị Collection được merge theo vùng bảng (mail merge region); content control được điền theo tag/title; ảnh trong shape được thay theo AlternativeText.

Với dữ liệu bảng cho Aspose.Cells, đánh dấu class bằng @DataTable:

@DataTable(namingStrategy = DataTable.NamingStrategy.SNAKE)
public class BangDoiTuong {
    private String maDoiTuong;
    private String tenDoiTuong;
}

Lưu ý

• License Aspose nằm cố định tại classpath aspose-license.xml và đã được đóng gói sẵn trong dependency; license nạp bất đồng bộ lúc khởi động, cần đảm bảo license hợp lệ trước khi xuất tài liệu.
• ExportType.EXCEL chưa được DefaultDocExporter hỗ trợ, sẽ ném EXP4000; template không tìm thấy hoặc lỗi đọc/ghi bọc thành EXP5000.
• Cấu hình duy nhất là property govex.aspose.template như bảng trên.
• govex-cloud-template và govex-cloud-onlyoffice dùng dependency này làm nền tảng sinh và chuẩn hóa văn bản.