PDF 模板生成实战：iText 5.x/9.x 方案对比与开源替代

<!-- pom.xml -->
<dependencies>
    <!-- iText 5.x（注意许可证） -->
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itextpdf</artifactId>
        <version>5.5.13.4</version>
    </dependency>
    <!-- iTextAsian 中文字体支持（如需） -->
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext-asian</artifactId>
        <version>5.2.0</version>
    </dependency>
</dependencies>

import com.itextpdf.text.DocumentException;
import com.itextpdf.text.pdf.AcroFields;
import com.itextpdf.text.pdf.BaseFont;
import com.itextpdf.text.pdf.PdfReader;
import com.itextpdf.text.pdf.PdfStamper;

import java.io.*;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * PDF 表单填充工具类（基于 iText 5.x）
 *
 * 功能：读取 PDF 模板 → 填充表单域 → 输出新 PDF
 */
public class PdfUtil {

    /**
     * 默认中文字体路径（根据部署环境调整）
     * 推荐将字体文件放在 resources/fonts/ 下随项目打包
     */
    private static final String FONT_PATH = "/fonts/simsun.ttc";

    /**
     * 填充 PDF 模板并输出到指定路径
     *
     * @param templatePath  PDF 模板文件路径
     * @param outputPath    输出 PDF 路径
     * @param fieldData     表单域数据（key = 域名, value = 填充值）
     * @throws Exception    文件读写或文档处理异常
     */
    public static void fillPdf(String templatePath,
                                String outputPath,
                                Map<String, String> fieldData) throws Exception {
        // 读取模板
        PdfReader reader = new PdfReader(templatePath);
        // 创建 Stamper（true = 追加模式，false = 覆盖）
        PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(outputPath));

        try {
            // 获取表单域
            AcroFields form = stamper.getAcroFields();

            // 嵌入中文字体（关键！不嵌入中文会显示为方块）
            BaseFont bfChinese = BaseFont.createFont(
                    FONT_PATH + ",0",          // ",0" 指定 TTC 字体集合中的第 0 个字体
                    BaseFont.IDENTITY_H,       // 水平书写
                    BaseFont.EMBEDDED           // 嵌入字体到 PDF
            );
            form.addSubstitutionFont(bfChinese);

            // 遍历填充数据
            for (Map.Entry<String, String> entry : fieldData.entrySet()) {
                String fieldName = entry.getKey();
                String fieldValue = entry.getValue();

                if (fieldValue == null) {
                    fieldValue = "";
                }

                // 判断字段类型
                int fieldType = form.getFieldType(fieldName);
                if (fieldType == AcroFields.FIELD_TYPE_CHECKBOX) {
                    // Checkbox 处理：值为 "Yes" 时勾选
                    form.setField(fieldName, "Yes");
                    // 如果需要取消勾选，传空字符串
                    // form.setField(fieldName, "");
                } else {
                    // 普通文本域
                    form.setField(fieldName, fieldValue);
                }
            }

            // 关键：设置为不可编辑（flat），表单域变为静态内容
            stamper.setFormFlattening(true);

        } finally {
            stamper.close();
            reader.close();
        }
    }

    /**
     * 批量生成 PDF
     *
     * @param templatePath  模板路径
     * @param outputDir     输出目录
     * @param dataList      批量数据列表，每条数据对应一份 PDF
     * @param nameField     用于生成文件名的字段名（如 "policyNo"）
     * @throws Exception    处理异常
     */
    public static void batchFill(String templatePath,
                                  String outputDir,
                                  List<Map<String, String>> dataList,
                                  String nameField) throws Exception {
        File dir = new File(outputDir);
        if (!dir.exists()) {
            dir.mkdirs();
        }

        for (int i = 0; i < dataList.size(); i++) {
            Map<String, String> data = dataList.get(i);
            // 用指定字段值或序号命名
            String fileName = data.getOrDefault(nameField, String.valueOf(i + 1));
            String outputPath = outputDir + File.separator + fileName + ".pdf";
            fillPdf(templatePath, outputPath, data);
        }
    }
}

// ❌ 错误写法：直接用路径，TTC 文件会报错
BaseFont bf = BaseFont.createFont("/fonts/simsun.ttc", BaseFont.IDENTITY_H, BaseFont.EMBEDDED);

// ✅ 正确写法：TTC 文件必须指定字体索引
// ",0" 表示 TTC 集合中的第 0 个字体（SimSun 宋体）
// ",1" 表示第 1 个字体（如 SimSun 粗体）
BaseFont bf = BaseFont.createFont("/fonts/simsun.ttc,0", BaseFont.IDENTITY_H, BaseFont.EMBEDDED);

// ✅ 也可以从 classpath 加载
InputStream is = PdfUtil.class.getResourceAsStream("/fonts/simsun.ttc");
byte[] fontBytes = is.readAllBytes();
BaseFont bf = BaseFont.createFont("simsun.ttc,0", BaseFont.IDENTITY_H, BaseFont.EMBEDDED, null, fontBytes, null);

/**
 * 设置 Checkbox 勾选样式
 *
 * @param form       AcroFields 对象
 * @param fieldName  Checkbox 域名
 * @param checked    是否勾选
 */
public static void setCheckbox(AcroFields form, String fieldName, boolean checked) {
    if (checked) {
        form.setField(fieldName, "Yes");
        // 尝试切换外观为 check（✓）
        // 注意：这取决于模板中定义的外观名称
        // 如果模板是用 Word 转的 PDF，外观名称可能是 "Yes", "1", "On" 等
        // 需要逐一尝试
        String[] states = form.getAppearanceStates(fieldName);
        System.out.println("可用状态: " + java.util.Arrays.toString(states));
    } else {
        // 取消勾选：传空或 Off
        form.setField(fieldName, "Off");
    }
}

import java.util.HashMap;
import java.util.Map;

public class PdfDemo {
    public static void main(String[] args) throws Exception {
        // 准备数据
        Map<String, String> data = new HashMap<>();
        data.put("userName", "张三");
        data.put("policyNo", "POL-2024-001234");
        data.put("effectiveDate", "2024年01月01日");
        data.put("expiryDate", "2025年01月01日");
        data.put("premium", "￥12,800.00");
        data.put("isAgree", "Yes");  // Checkbox

        // 填充 PDF
        PdfUtil.fillPdf(
                "/templates/policy_template.pdf",  // 模板路径
                "/output/policy_001.pdf",           // 输出路径
                data
        );

        System.out.println("PDF 生成完成！");
    }
}

<dependencies>
    <!-- iText 9 核心 -->
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext7-core</artifactId>
        <version>9.6.0</version>
        <type>pom</type>
    </dependency>
    <!-- 中文字体支持 -->
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>font-asian</artifactId>
        <version>9.6.0</version>
    </dependency>
</dependencies>

import com.itextpdf.forms.PdfAcroForm;
import com.itextpdf.forms.fields.PdfFormField;
import com.itextpdf.kernel.font.PdfFont;
import com.itextpdf.kernel.font.PdfFontFactory;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfReader;
import com.itextpdf.kernel.pdf.PdfWriter;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

/**
 * PDF 表单填充工具类（基于 iText 9.x）
 *
 * iText 9.x 的 API 更现代，采用 Builder 模式
 */
public class PdfUtilV7 {

    private static final String FONT_PATH = "/fonts/simsun.ttc";

    /**
     * 填充 PDF 模板
     *
     * @param templatePath 模板路径
     * @param outputPath   输出路径
     * @param fieldData    表单数据
     * @throws IOException IO 异常
     */
    public static void fillPdf(String templatePath,
                                String outputPath,
                                Map<String, String> fieldData) throws IOException {
        // iText 9 使用 PdfDocument 统一管理
        PdfDocument pdfDoc = new PdfDocument(
                new PdfReader(templatePath),
                new PdfWriter(outputPath)
        );

        try {
            // 获取表单
            PdfAcroForm form = PdfAcroForm.getAcroForm(pdfDoc, true);

            // 加载中文字体
            PdfFont chineseFont = PdfFontFactory.createFont(
                    FONT_PATH + ",0",
                    "Identity-H"    // 编码方式
            );

            // 填充字段
            Map<String, PdfFormField> fields = form.getAllFormFields();
            for (Map.Entry<String, String> entry : fieldData.entrySet()) {
                String fieldName = entry.getKey();
                String fieldValue = entry.getValue();

                PdfFormField field = fields.get(fieldName);
                if (field == null) {
                    System.err.println("字段不存在: " + fieldName);
                    continue;
                }

                // 设置值和字体
                field.setValue(fieldValue != null ? fieldValue : "");
                field.setFont(chineseFont);
                field.setFontSize(10);  // 根据模板调整
            }

            // 扁平化（不可编辑）
            form.flattenFields();

        } finally {
            pdfDoc.close();
        }
    }
}

import org.apache.pdfbox.Loader;
import org.apache.pdfbox.cos.COSName;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDResources;
import org.apache.pdfbox.pdmodel.font.PDType0Font;
import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
import org.apache.pdfbox.pdmodel.interactive.form.PDField;

import java.io.File;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.Map;

/**
 * PDF 表单填充工具类（基于 Apache PDFBox 3.0）
 *
 * 许可证：Apache 2.0，商业项目完全免费
 */
public class PdfBoxUtil {

    private static final String FONT_PATH = "/fonts/simsun.ttc";

    /**
     * 填充 PDF 模板
     *
     * @param templatePath 模板路径
     * @param outputPath   输出路径
     * @param fieldData    表单数据
     * @throws IOException IO 异常
     */
    public static void fillPdf(String templatePath,
                                String outputPath,
                                Map<String, String> fieldData) throws IOException {
        // PDFBox 3.0 使用 Loader 加载文档
        try (PDDocument document = Loader.loadPDF(new File(templatePath))) {
            PDAcroForm acroForm = document.getDocumentCatalog().getAcroForm();

            if (acroForm == null) {
                throw new IllegalArgumentException("PDF 没有表单域");
            }

            // 加载中文字体，并设置为表单默认外观字体
            PDResources resources = acroForm.getDefaultResources();
            if (resources == null) {
                resources = new PDResources();
                acroForm.setDefaultResources(resources);
            }
            try (InputStream fontStream = PdfBoxUtil.class.getResourceAsStream(FONT_PATH)) {
                if (fontStream == null) {
                    throw new FileNotFoundException("字体文件不存在: " + FONT_PATH);
                }
                PDType0Font chineseFont = PDType0Font.load(document, fontStream);
                COSName fontName = resources.add(chineseFont);
                acroForm.setDefaultAppearance("/" + fontName.getName() + " 10 Tf 0 g");
            }

            // 填充字段
            for (Map.Entry<String, String> entry : fieldData.entrySet()) {
                String fieldName = entry.getKey();
                String fieldValue = entry.getValue();

                PDField field = acroForm.getField(fieldName);
                if (field == null) {
                    System.err.println("字段不存在: " + fieldName);
                    continue;
                }

                // 设置字段值
                field.setValue(fieldValue != null ? fieldValue : "");
            }

            // 扁平化表单（不可编辑）
            acroForm.flatten();

            // 保存
            document.save(new File(outputPath));
        }
    }

    /**
     * 批量生成 PDF
     */
    public static void batchFill(String templatePath,
                                  String outputDir,
                                  java.util.List<Map<String, String>> dataList,
                                  String nameField) throws IOException {
        File dir = new File(outputDir);
        if (!dir.exists()) {
            dir.mkdirs();
        }

        // 一次性读取模板到内存，复用解析结果
        byte[] templateBytes = java.nio.file.Files.readAllBytes(
                java.nio.file.Paths.get(templatePath));

        for (int i = 0; i < dataList.size(); i++) {
            Map<String, String> data = dataList.get(i);
            String fileName = data.getOrDefault(nameField, String.valueOf(i + 1));
            String outputPath = outputDir + File.separator + fileName + ".pdf";

            // 每次从字节数组加载（避免重复解析模板文件）
            try (PDDocument document = Loader.loadPDF(templateBytes)) {
                PDAcroForm acroForm = document.getDocumentCatalog().getAcroForm();
                for (Map.Entry<String, String> entry : data.entrySet()) {
                    PDField field = acroForm.getField(entry.getKey());
                    if (field != null) {
                        field.setValue(entry.getValue() != null ? entry.getValue() : "");
                    }
                }
                acroForm.flatten();
                document.save(new File(outputPath));
            }
        }
    }
}

import com.lowagie.text.pdf.AcroFields;
import com.lowagie.text.pdf.BaseFont;
import com.lowagie.text.pdf.PdfReader;
import com.lowagie.text.pdf.PdfStamper;

import java.io.File;
import java.io.FileOutputStream;
import java.util.List;
import java.util.Map;

/**
 * PDF 表单填充工具类（基于 OpenPDF）
 * API 与 iText 5.x 几乎完全一致
 */
public class OpenPdfUtil {

    private static final String FONT_PATH = "/fonts/simsun.ttc";

    /**
     * 填充 PDF 表单
     */
    public static void fillPdf(String templatePath,
                                String outputPath,
                                Map<String, String> fieldData) throws Exception {
        PdfReader reader = new PdfReader(templatePath);
        PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(outputPath));

        try {
            AcroFields form = stamper.getAcroFields();

            // 嵌入中文字体
            BaseFont bfChinese = BaseFont.createFont(
                    FONT_PATH + ",0",
                    BaseFont.IDENTITY_H,
                    BaseFont.EMBEDDED
            );
            form.addSubstitutionFont(bfChinese);

            // 填充字段
            for (Map.Entry<String, String> entry : fieldData.entrySet()) {
                String key = entry.getKey();
                String value = entry.getValue();
                if (value == null) value = "";

                // 判断字段类型
                int fieldType = form.getFieldType(key);
                if (fieldType == AcroFields.FIELD_TYPE_CHECKBOX) {
                    // Checkbox
                    form.setField(key, "Yes".equals(value) ? "Yes" : "Off");
                } else if (fieldType == AcroFields.FIELD_TYPE_RADIOBUTTON) {
                    form.setField(key, value);
                } else {
                    form.setField(key, value);
                }
            }

            // 表单域转静态内容（必须！）
            stamper.setFormFlattening(true);
        } finally {
            stamper.close();
            reader.close();
        }
    }

    /**
     * 批量填充（复用模板字节数组）
     */
    public static void batchFill(byte[] templateBytes,
                                  String outputDir,
                                  List<Map<String, String>> dataList) throws Exception {
        for (int i = 0; i < dataList.size(); i++) {
            PdfReader reader = new PdfReader(templateBytes);
            String outputPath = outputDir + File.separator + "doc_" + i + ".pdf";
            PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(outputPath));

            AcroFields form = stamper.getAcroFields();
            BaseFont bfChinese = BaseFont.createFont(
                    FONT_PATH + ",0", BaseFont.IDENTITY_H, BaseFont.EMBEDDED);
            form.addSubstitutionFont(bfChinese);

            for (Map.Entry<String, String> entry : dataList.get(i).entrySet()) {
                form.setField(entry.getKey(), entry.getValue());
            }

            stamper.setFormFlattening(true);
            stamper.close();
            reader.close();
        }
    }
}

// iText 5.x
import com.itextpdf.text.pdf.BaseFont;
import com.itextpdf.text.pdf.PdfReader;
import com.itextpdf.text.pdf.PdfStamper;
import com.itextpdf.text.pdf.AcroFields;

// OpenPDF（只改包名）
import com.lowagie.text.pdf.BaseFont;
import com.lowagie.text.pdf.PdfReader;
import com.lowagie.text.pdf.PdfStamper;
import com.lowagie.text.pdf.AcroFields;

import com.lowagie.text.pdf.BaseFont;
import org.xhtmlrenderer.pdf.ITextRenderer;

import java.io.File;
import java.io.FileOutputStream;

public class HtmlToPdfUtil {

    public static void convert(String htmlPath, String pdfPath) throws Exception {
        ITextRenderer renderer = new ITextRenderer();

        // 注册中文字体
        renderer.getFontResolver().addFont(
                "/fonts/simsun.ttc",
                BaseFont.IDENTITY_H,
                BaseFont.EMBEDDED
        );

        renderer.setDocument(new File(htmlPath));
        renderer.layout();
        try (FileOutputStream out = new FileOutputStream(pdfPath)) {
            renderer.createPDF(out);
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8"/>
    <style>
        body { font-family: SimSun; font-size: 12pt; }
        .header { text-align: center; font-size: 18pt; font-weight: bold; }
        .field { color: #333; border-bottom: 1px solid #000; }
        table { width: 100%; border-collapse: collapse; }
        td, th { border: 1px solid #000; padding: 6px; }
    </style>
</head>
<body>
    <div class="header">商品购买合同</div>
    <p>甲方：<span class="field">${buyerName}</span></p>
    <p>乙方：<span class="field">${sellerName}</span></p>
    <table>
        <tr><th>商品</th><th>数量</th><th>单价</th></tr>
        <tr><td>${productName}</td><td>${quantity}</td><td>${price}</td></tr>
    </table>
</body>
</html>

import org.docx4j.Docx4J;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

import java.io.File;
import java.io.FileOutputStream;

public class WordToPdfUtil {

    public static void convert(String docxPath, String pdfPath) throws Exception {
        WordprocessingMLPackage word = WordprocessingMLPackage.load(new File(docxPath));
        try (FileOutputStream out = new FileOutputStream(pdfPath)) {
            Docx4J.toPDF(word, out);
        }
    }
}

/**
 * 优化建议：
 * 1. 复用模板字节数组 —— 每次读文件会增加 IO 开销
 * 2. 使用字节数组流 —— 减少磁盘 IO
 * 3. 线程池并行 —— 注意每个线程独立的文档实例
 */
public static void batchFillOptimized(String templatePath,
                                        String outputDir,
                                        List<Map<String, String>> dataList) throws Exception {
    // 一次性读取模板到内存
    byte[] templateBytes = Files.readAllBytes(Paths.get(templatePath));

    // 使用线程池并行生成
    ExecutorService pool = Executors.newFixedThreadPool(
            Runtime.getRuntime().availableProcessors()
    );

    List<Future<?>> futures = new ArrayList<>();
    for (int i = 0; i < dataList.size(); i++) {
        final int index = i;
        futures.add(pool.submit(() -> {
            try {
                // 每个线程独立创建 Reader（线程安全）
                PdfReader reader = new PdfReader(templateBytes);
                String outputPath = outputDir + "/doc_" + index + ".pdf";
                PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(outputPath));
                // ... 填充逻辑同上
                stamper.setFormFlattening(true);
                stamper.close();
                reader.close();
            } catch (Exception e) {
                throw new RuntimeException("生成第 " + index + " 份 PDF 失败", e);
            }
        }));
    }

    // 等待全部完成
    for (Future<?> f : futures) {
        f.get();
    }
    pool.shutdown();
}

需要生成/填充 PDF？
├── 是
│   ├── 商业项目 + 零预算？
│   │   ├── 是 → PDFBox 3.0（Apache 2.0）
│   │   └── 否 → iText 9.x 商业版
│   ├── 从 iText 5.x 迁移？
│   │   └── 是 → OpenPDF 3.0（改包名即可）
│   ├── 开源项目？
│   │   └── 是 → iText 9.x（功能最强）
│   └── 只需简单表单填充？
│       └── 是 → PDFBox 3.0（最安全）
└── 否 → 不需要 PDF 库