基于Java的Word文档自动生成与排版实战

本文还有配套的精品资源，点击获取

简介：在IT领域，自动生成排版规范的Word文档广泛应用于数据报告、自动化办公和批量文本处理。通过Java语言结合Apache POI等工具库，开发者可实现对.docx文件的读写与样式控制，支持字体、段落、表格、图片、页眉页脚等元素的精确排版，并能通过模板机制动态填充数据，完成高效自动化导出。该技术已在金融报表、合同生成、邮件合并等场景中发挥重要作用。本文介绍完整的Word文档生成流程，涵盖核心API使用、页面元素操作、性能优化及异常处理，帮助开发者构建稳定高效的文档自动化系统。

1. Apache POI框架简介与核心组件（HWPF/XWPF）

Apache POI概述与核心模块

Apache POI是Java平台处理Microsoft Office文档的权威开源库，支持Word、Excel、PowerPoint等格式的读写操作。其核心模块中， XWPF 用于处理基于OpenXML标准的 .docx 文件，而 HWPF 则负责旧版二进制 .doc 格式。

// Maven依赖配置示例
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.3</version>
</dependency>

XWPF采用DOM模型解析文档，通过 XWPFDocument 、 XWPFParagraph 、 XWPFRun 等对象构建层次化结构，便于编程控制。相较之下，HWPF功能有限且维护较少，推荐新项目统一使用XWPF。本章为后续自动化文档生成奠定理论与环境基础。

2. 使用XWPF创建与操作.docx文档基础流程

在Java应用开发中，自动生成结构化、排版规范的Word文档已成为报表生成、合同定制、公文自动化等场景中的核心需求。Apache POI的XWPF模块作为处理 .docx 格式文件的核心工具包，提供了对OpenXML标准的完整封装，使开发者可以通过面向对象的方式构建复杂的Word文档。本章将系统性地阐述如何基于XWPF完成从零开始创建文档的基础流程，涵盖文档初始化、内容组织逻辑以及模板驱动的动态修改三大关键环节。通过深入剖析 XWPFDocument 、 XWPFParagraph 和 XWPFRun 之间的层级关系，并结合代码示例与流程图解，帮助读者建立清晰的操作模型。

2.1 文档对象的初始化与基本结构构建

2.1.1 创建空白XWPFDocument实例

在使用Apache POI进行Word文档操作之前，必须首先获得一个可操作的文档容器——即 XWPFDocument 类的实例。该类是整个XWPF模块的根对象，代表一个完整的 .docx 文档，其内部遵循Office Open XML（OOXML）标准组织内容，包括正文、样式表、图像资源、页眉页脚等多个部分。

创建一个全新的空白文档非常简单，只需调用无参构造函数即可：

import org.apache.poi.xwpf.usermodel.XWPFDocument;

public class DocxCreator {
    public static void main(String[] args) {
        // 创建一个新的空白.docx文档
        XWPFDocument document = new XWPFDocument();
        // 后续操作在此基础上展开
    }
}

代码逻辑逐行解读：

• 第1行：导入 XWPFDocument 类，这是所有文档操作的起点。
• 第5行：通过 new XWPFDocument() 初始化一个空文档对象。此时内存中已存在符合 .docx 结构的ZIP归档骨架，包含必要的XML部件如 [Content_Types].xml 、 word/document.xml 等，但尚未添加任何用户可见内容。

此对象不仅支持写入文本、表格、图片等内容，还维护着文档级别的元数据（如作者、标题）、主题设置及底层OPC（Open Packaging Conventions）包结构。值得注意的是， XWPFDocument 实现了 Closeable 接口，因此在使用完毕后必须显式关闭以释放流资源，避免内存泄漏。

属性	说明
document.xml	存储主文档内容（段落、表格等）
styles.xml	定义文档使用的样式集合
settings.xml	包含页面布局、兼容性选项等设置
_rels/.rels	描述各部件之间的引用关系

下面是一个简单的mermaid流程图，展示文档初始化后的内部结构组成：

graph TD
    A[XWPFDocument] --> B[[OPC Package]]
    B --> C["[Content_Types].xml"]
    B --> D[word/_rels/document.xml.rels]
    B --> E[word/document.xml]
    B --> F[word/styles.xml]
    B --> G[word/theme/theme1.xml]
    E --> H[Body Content: Paragraphs, Tables]

该图表明， XWPFDocument 本质上是对一个ZIP压缩包的抽象，其中每个XML文件对应不同的功能模块。当执行 new XWPFDocument() 时，这些基础组件会被自动创建并加载到内存中，为后续的内容插入提供支撑。

2.1.2 添加段落与文本内容的基本方法

一旦获得 XWPFDocument 实例，下一步就是向其中添加可读内容。最基础的内容单元是段落（ XWPFParagraph ），而段落由一个或多个文本运行（ XWPFRun ）构成。这种设计源于OpenXML中“段落-运行”的嵌套结构，允许在同一段内实现字体、颜色等样式的局部变化。

以下代码演示如何添加一个包含纯文本的段落：

import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.poi.xwpf.usermodel.XWPFRun;

public class AddParagraphExample {
    public static void main(String[] args) throws Exception {
        XWPFDocument document = new XWPFDocument();

        // 创建新段落
        XWPFParagraph paragraph = document.createParagraph();
        // 获取段落中的文本运行对象
        XWPFRun run = paragraph.createRun();
        run.setText("这是一个使用Apache POI生成的示例段落。");

        // 保存文档
        try (FileOutputStream out = new FileOutputStream("output/basic.docx")) {
            document.write(out);
        }

        document.close();
    }
}

参数说明与逻辑分析：

• document.createParagraph() ：向文档末尾追加一个新的段落对象，并返回对该段落的引用。每调用一次即新增一段。
• paragraph.createRun() ：在指定段落中创建一个文本运行（Run）。一个段落可以有多个Run，用于实现不同样式的拼接。
• run.setText(String text) ：设置当前Run中的文本内容。注意此方法会覆盖原有文本。
• document.write(OutputStream) ：将整个文档结构序列化为 .docx 文件并输出至指定流。

上述代码生成的文档将在Word中显示一行中文文本。若需换行，不能直接使用 \n ，而应调用 run.addBreak() 或创建新的段落来实现自然分段。

此外，可通过链式调用来简化代码：

document.createParagraph()
         .createRun()
         .setText("链式调用方式添加文本");

这种方式提升了代码可读性，尤其适用于快速原型开发。

2.1.3 文档保存与输出流管理

文档编辑完成后，必须将其持久化为物理文件或字节数组，以便传输或展示。XWPF提供了两种主要输出方式：写入文件流或写入字节流。

写入本地文件

FileOutputStream fileOut = new FileOutputStream("report.docx");
document.write(fileOut);
fileOut.close(); // 推荐使用try-with-resources

写入字节数组（适用于Web响应）

ByteArrayOutputStream baos = new ByteArrayOutputStream();
document.write(baos);
byte[] docBytes = baos.toByteArray();
baos.close();

推荐始终使用 try-with-resources 语句确保资源正确释放：

try (FileOutputStream out = new FileOutputStream("output.docx")) {
    document.write(out);
} catch (IOException e) {
    e.printStackTrace();
} finally {
    document.close();
}

输出方式	适用场景	性能特点
FileOutputStream	本地存储、批量导出	高效稳定
ByteArrayOutputStream	Web服务返回、内存缓存	占用堆空间，适合小文档
ServletOutputStream	Spring MVC控制器直接下载	需配合HTTP头设置

错误处理方面，常见异常包括：
- IOException ：磁盘满、权限不足、路径无效
- NullPointerException ：未初始化document或paragraph
- InvalidFormatException ：模板损坏或不符合OOXML规范

务必在生产环境中加入日志记录与异常兜底机制，保障系统的健壮性。

2.2 段落与文本单元的组织逻辑

2.2.1 XWPFParagraph与XWPFRun的关系解析

理解 XWPFParagraph 与 XWPFRun 之间的协作机制，是掌握精细排版控制的关键。二者的关系类似于HTML中的 <p> 标签与 <span> 标签：段落定义整体段落级格式（如对齐、缩进），而Run则负责控制其中某一部分文字的具体显示效果（如字体、颜色）。

一个典型的段落结构如下所示：

[Paragraph]
 └── [Run #1] "这是一段"
 └── [Run #2] "加粗的文字"
 └── [Run #3] "和普通文字混合"

对应的Java代码实现：

XWPFParagraph p = document.createParagraph();
XWPFRun r1 = p.createRun();
r1.setText("这是一段");

XWPFRun r2 = p.createRun();
r2.setBold(true);
r2.setColor("FF0000");
r2.setText("加粗的文字");

XWPFRun r3 = p.createRun();
r3.setText("和普通文字混合");

逐行分析：
- 第2行：创建段落，作为所有Run的容器。
- 第3–4行：第一个Run插入普通文本。
- 第6–8行：第二个Run设置加粗与红色字体（RGB值 FF0000 ），再插入特定文本。
- 第10–11行：第三个Run恢复默认样式继续输入。

由此可知， 同一段落内的多个Run共享段落级属性 （如对齐方式），但各自拥有独立的字符级样式。这种分离设计使得复杂排版成为可能，例如法律条文中“第X条”加粗、“内容”正常、“关键词”高亮等。

下图用mermaid表示其结构关系：

classDiagram
    class XWPFDocument {
        +List~XWPFParagraph~ getParagraphs()
        +XWPFParagraph createParagraph()
    }
    class XWPFParagraph {
        +List~XWPFRun~ getRuns()
        +XWPFRun createRun()
        +setAlignment(ParagraphAlignment align)
    }
    class XWPFRun {
        +void setText(String text)
        +void setBold(boolean bold)
        +void setColor(String hexColor)
        +void setFontFamily(String font)
    }

    XWPFDocument "1" *-- "0..*" XWPFParagraph : contains
    XWPFParagraph "1" *-- "1..*" XWPFRun : contains

该UML类图清晰展示了三者间的聚合关系：文档包含多个段落，每个段落又包含至少一个Run。

2.2.2 多段落顺序插入与内容追加策略

在实际应用中，往往需要按顺序插入多个段落，形成结构化的文档内容。XWPF默认采用“追加模式”，即每次调用 createParagraph() 都会在文档末尾添加新段。

考虑如下场景：生成一份会议纪要，依次包含标题、时间、地点、议题列表。

String[] topics = {"项目进度汇报", "预算调整讨论", "人员变动通报"};

// 标题段落
XWPFParagraph title = document.createParagraph();
title.setAlignment(ParagraphAlignment.CENTER);
XWPFRun titleRun = title.createRun();
titleRun.setBold(true);
titleRun.setFontSize(16);
titleRun.setText("会议纪要");

// 时间信息
addSimpleParagraph(document, "会议时间：2025年4月5日");

// 地点信息
addSimpleParagraph(document, "会议地点：第三会议室");

// 议题列表
for (String topic : topics) {
    XWPFParagraph item = document.createParagraph();
    item.setIndentLeft(400); // 左缩进约2字符宽度
    XWPFRun run = item.createRun();
    run.setText("• " + topic);
}

辅助方法定义：

private static void addSimpleParagraph(XWPFDocument doc, String text) {
    XWPFParagraph p = doc.createParagraph();
    XWPFRun r = p.createRun();
    r.setText(text);
}

此策略的优点在于逻辑清晰、易于维护。但对于大型文档（如上百页报告），频繁调用 createParagraph() 可能导致内存占用过高。此时可结合第六章介绍的流式处理方案优化性能。

2.2.3 特殊字符与换行符的正确处理方式

在跨平台环境下处理文本时，特殊字符的渲染容易出现问题。例如，直接使用 \n 换行在Word中不会生效，因为 .docx 使用OpenXML的 <w:br/> 标签表示软回车。

正确的做法是使用 XWPFRun 提供的API：

XWPFRun run = paragraph.createRun();
run.setText("第一行");
run.addBreak(); // 软换行（Shift+Enter）
run.setText("第二行");
run.addBreak(BreakType.PAGE); // 分页符
run.setText("第三页开始");

支持的换行类型包括：

BreakType	效果	对应Word操作
TEXT_WRAPPING	自动换行	Enter
PAGE	分页符	Ctrl+Enter
COLUMN	分栏符	—
LINE_SEPARATOR	行分隔符	—

此外，对于包含占位符（如 ${name} ）或XML敏感字符（ < , > , & ）的文本，XWPF会自动转义以防止解析错误。但在某些高级替换场景中，建议预处理字符串：

String safeText = userInput.replaceAll("[<>\"&]", "");

同时注意编码问题：确保输入文本使用UTF-8编码，特别是在处理中文、日文等多字节字符时，避免出现乱码。

2.3 基于模板的文档加载与修改

2.3.1 从现有.docx文件加载XWPFDocument

相较于从零构建，基于模板的文档生成更为高效且贴近实际业务需求。许多企业已有标准化的合同、报告模板，只需填充变量即可复用。

加载模板的方法如下：

FileInputStream templateIn = new FileInputStream("template/contract_template.docx");
XWPFDocument document = new XWPFDocument(templateIn);

// 修改内容...
templateIn.close();

Apache POI会在加载时解析模板中的所有XML节点，重建内存中的对象模型。这意味着你可以像操作新建文档一样访问段落、表格、图片等元素。

重要提示：
- 模板文件必须是合法的 .docx （即ZIP压缩的OpenXML文档）
- 不支持旧版 .doc 格式（需使用HWPF）
- 若模板过大（>10MB），建议启用缓冲流提升读取效率：

BufferedInputStream bis = new BufferedInputStream(
    new FileInputStream("large_template.docx")
);
XWPFDocument doc = new XWPFDocument(OPCPackage.open(bis));

2.3.2 模板文档的结构分析与可编辑区域识别

为了实现精准的内容替换，必须先识别模板中的“可编辑区域”。常见做法是在模板中使用占位符标记，如：

客户名称：${client_name}
签订日期：${sign_date}
总金额：${amount} 元

程序的任务是遍历所有段落，查找并替换这些占位符。

以下是通用的段落扫描逻辑：

Map<String, String> data = new HashMap<>();
data.put("${client_name}", "张三科技有限公司");
data.put("${sign_date}", "2025-04-05");
data.put("${amount}", "88,000");

for (XWPFParagraph p : document.getParagraphs()) {
    List<XWPFRun> runs = p.getRuns();
    if (runs == null || runs.isEmpty()) continue;

    String text = p.getText();
    for (Map.Entry<String, String> entry : data.entrySet()) {
        if (text.contains(entry.getKey())) {
            for (XWPFRun run : runs) {
                String runText = run.getText(0);
                if (runText != null && runText.contains(entry.getKey())) {
                    run.setText(runText.replace(entry.getKey(), entry.getValue()), 0);
                }
            }
        }
    }
}

关键点说明：
- getParagraphs() 返回文档中所有段落的列表，按顺序排列。
- getRuns() 获取段落内所有文本运行，某些情况下占位符可能被拆分在多个Run中。
- 使用 getText(0) 获取Run的原始文本（索引0表示唯一文本节点）。
- 替换操作需保留Run的样式属性，仅更改文本内容。

对于表格中的单元格内容，也需类似遍历：

for (XWPFTable table : document.getTables()) {
    for (XWPFTableRow row : table.getRows()) {
        for (XWPFTableCell cell : row.getTableCells()) {
            for (XWPFParagraph p : cell.getParagraphs()) {
                // 同上替换逻辑
            }
        }
    }
}

2.3.3 动态内容替换的初步实践

综合以上技术，实现一个完整的模板填充示例：

public class TemplateFiller {
    public static void fillContractTemplate() throws Exception {
        try (FileInputStream in = new FileInputStream("template/contract.docx")) {
            XWPFDocument doc = new XWPFDocument(in);

            Map<String, String> placeholders = Map.of(
                "${company}", "星辰软件有限公司",
                "${project}", "智能客服系统开发",
                "${price}", "¥1,200,000.00",
                "${date}", LocalDate.now().toString()
            );

            // 遍历段落替换
            replaceInParagraphs(doc.getParagraphs(), placeholders);
            // 遍历表格替换
            for (XWPFTable tbl : doc.getTables()) {
                replaceInTable(tbl, placeholders);
            }

            try (FileOutputStream out = new FileOutputStream("output/filled_contract.docx")) {
                doc.write(out);
            }
            doc.close();
        }
    }

    private static void replaceInParagraphs(List<XWPFParagraph> paragraphs, Map<String, String> map) {
        for (XWPFParagraph p : paragraphs) {
            String text = p.getText();
            if (text == null) continue;
            boolean found = false;
            for (String key : map.keySet()) {
                if (text.contains(key)) {
                    found = true;
                    break;
                }
            }
            if (found) {
                for (XWPFRun run : p.getRuns()) {
                    String rText = run.getText(0);
                    if (rText != null) {
                        for (Map.Entry<String, String> e : map.entrySet()) {
                            if (rText.contains(e.getKey())) {
                                rText = rText.replace(e.getKey(), e.getValue());
                                run.setText(rText, 0);
                            }
                        }
                    }
                }
            }
        }
    }

    private static void replaceInTable(XWPFTable table, Map<String, String> map) {
        for (XWPFTableRow row : table.getRows()) {
            for (XWPFTableCell cell : row.getTableCells()) {
                replaceInParagraphs(cell.getParagraphs(), map);
            }
        }
    }
}

该程序能够准确识别并替换分布在段落和表格中的占位符，生成个性化的合同文档。为进一步提升灵活性，可在后续章节引入正则表达式匹配、条件判断、循环列表插入等高级特性。

3. 字体、字号、颜色及段落样式的编程控制（XWPFRun与XWPFParagraph）

在自动化生成Word文档的过程中，仅仅实现内容的填充是远远不够的。为了满足企业级文档输出对排版美观性、专业性和一致性的高要求，必须对文本和段落的样式进行精细化编程控制。Apache POI 的 XWPF 模块通过 XWPFRun 和 XWPFParagraph 两个核心类分别管理 字符级格式 与 段落级格式 ，其设计遵循了 OpenXML 标准中关于文档结构的分层模型。深入理解这两个对象的属性设置机制、继承规则以及它们之间的协作方式，是实现高质量文档渲染的关键。

本章将从底层出发，系统剖析如何通过 Java 编程动态配置字体样式、颜色效果、段落对齐、缩进间距等视觉元素，并进一步探讨样式复用策略与自定义样式体系的构建方法。通过对 API 的深度调用示例、参数逻辑分析以及可视化流程图展示，帮助开发者建立起可维护、可扩展的文档样式控制架构。

3.1 文本样式控制：XWPFRun属性设置

XWPFRun 是 Apache POI 中表示“运行”（Run）这一概念的核心类，对应于 Word 文档中的一个连续文本片段，具有统一的字符格式。例如，在同一段落中，“这是 加粗 的文字”，其中“加粗”部分就是一个独立的 Run 对象，拥有不同于前后文本的字体属性。因此，要实现细粒度的文本格式化，就必须熟练掌握 XWPFRun 的各项属性设置方法。

3.1.1 字体名称、大小、加粗、斜体与下划线配置

在 XWPF 中，每个 XWPFRun 实例都可以单独设置字体族（Font Family）、字号（Size）、是否加粗（Bold）、斜体（Italic）、下划线（Underline）等基础属性。这些设置直接影响文本的呈现效果，适用于标题强调、关键词突出等场景。

以下是一个完整的代码示例，演示如何创建带有多种字体样式的段落：

import org.apache.poi.xwpf.usermodel.*;

public class FontExample {
    public static void main(String[] args) throws Exception {
        XWPFDocument document = new XWPFDocument();

        // 创建段落
        XWPFParagraph paragraph = document.createParagraph();
        XWPFRun run = paragraph.createRun();

        // 设置正常文本
        run.setText("这是一段普通文本，");
        run.setFontFamily("宋体");
        run.setFontSize(12);

        // 新建一个Run用于加粗斜体
        run = paragraph.createRun();
        run.setText("这是加粗斜体带下划线的文本");
        run.setFontFamily("微软雅黑");
        run.setFontSize(14);
        run.setBold(true);
        run.setItalic(true);
        run.setUnderline(UnderlinePatterns.SINGLE);

        // 保存文档
        try (FileOutputStream out = new FileOutputStream("font_example.docx")) {
            document.write(out);
        }
        document.close();
    }
}

代码逻辑逐行解读与参数说明：

行号	代码	解读
7	XWPFDocument document = new XWPFDocument();	初始化一个空的 .docx 文档容器，作为所有内容的父级结构。
9	XWPFParagraph paragraph = document.createParagraph();	向文档添加一个新的段落对象，后续文本将插入到该段落中。
10	XWPFRun run = paragraph.createRun();	在当前段落中创建第一个 Run，用于承载连续格式的文本。
12-14	setText , setFontFamily , setFontSize	分别设置文本内容、字体名称和字号（单位为磅）。注意：字体需系统支持，否则会回退到默认字体。
17-23	第二个 run = paragraph.createRun() 开始新 Run	关键点：每次调用 createRun() 都会开启一个新的格式区间，避免影响前文样式。
21	setUnderline(UnderlinePatterns.SINGLE)	设置单线下划线；其他可选值包括 DOUBLE , DOTTED , THICK 等，详见枚举类。

⚠️ 注意事项 ：
- 若在同一 run 上连续调用 setText() 多次，后一次会覆盖前一次内容。
- 不同 Run 必须分开创建才能实现混合样式。
- setFontFamily() 接受的是字体名字符串，建议使用常见中文字体如“宋体”、“黑体”、“微软雅黑”。

3.1.2 字体颜色与高亮效果的RGB值设定

除了基本字体属性外， XWPFRun 还支持通过 RGB 值精确控制字体颜色和背景高亮色。这对于制作彩色报告、错误提示或重点标注非常有用。

XWPFRun colorRun = paragraph.createRun();
colorRun.setText("这是红色字体并带有黄色高亮");
colorRun.setColor("FF0000");           // 设置字体颜色为红色（十六进制RGB）
colorRun.setHighlightColor(HighlightColor.YELLOW); // 设置背景高亮为黄色

更进一步地，还可以使用低层级 CT 对象直接操作 OpenXML 属性，以支持更多高亮类型或透明度控制：

// 使用底层 XML Bean 设置自定义高亮颜色（非标准色）
CTUnderline ctUnderline = CTUnderline.Factory.newInstance();
ctUnderline.setVal(STUnderline.NONE);
colorRun.getCTR().getXmlObject().set(CTUnderline.type, ctUnderline);

// 设置字体颜色（使用 CTRPr 类）
CTRPr rpr = colorRun.getCTR().getRPR();
if (rpr == null) rpr = colorRun.getCTR().addNewRPR();
CTColor color = CTColor.Factory.newInstance();
color.setVal("0000FF"); // 蓝色
rpr.setColor(color);

参数说明表：

方法	参数类型	可选值/说明
setColor(String hexColor)	String	六位十六进制颜色码（如 "FF0000" 表示红色）
setHighlightColor(HighlightColor color)	enum	提供预设色： YELLOW , GREEN , CYAN , MAGENTA , BLUE , RED , DARK_BLUE , DARK_CYAN 等
getCTR()	CTR	返回底层 XML bean，可用于高级定制（需熟悉 OOXML 结构）

💡 技巧提示 ：当需要设置非标准高亮色（如浅灰、橙色）时，可通过修改 w:highlight XML 节点的 val 属性实现，但兼容性可能受限于某些旧版 Word 解析器。

3.1.3 上标、下标及特殊字体效果的应用

在科学文档、数学公式或化学表达式中，常需使用上标（superscript）或下标（subscript）。 XWPFRun 提供了 setTextPosition() 方法来实现这一功能。

XWPFRun subscriptRun = paragraph.createRun();
subscriptRun.setText("H₂O 是水的分子式");

// 将 '2' 设为下标（位置负值表示下沉）
XWPFRun subRun = paragraph.createRun();
subRun.setText("2");
subRun.setTextPosition(-10); // 下沉 10 磅，典型下标值

XWPFRun normalRun = paragraph.createRun();
normalRun.setText("O 是水的分子式");

此外，还可结合 setCapitalization() 实现小型大写（Small Caps），或使用 setStrikeThrough() 添加删除线：

XWPFRun strikeRun = paragraph.createRun();
strikeRun.setText("此内容已被删除");
strikeRun.setStrikeThrough(true);

XWPFRun smallCapsRun = paragraph.createRun();
smallCapsRun.setText("小型大写文本");
smallCapsRun.setCapitalization(1); // 1 表示 small caps，0 表示正常

特殊效果对照表：

效果	方法	参数说明
上标	setTextPosition(positiveValue)	推荐值：+6 到 +10（单位：半磅）
下标	setTextPosition(negativeValue)	推荐值：-6 到 -10
删除线	setStrikeThrough(boolean)	true 启用删除线
小型大写	setCapitalization(int)	1=Small Caps, 0=Normal
阴影	setShadow(boolean)	支持，但渲染效果依赖客户端

📌 实践建议 ：
- 上/下标不宜频繁使用，应封装成工具方法提高可读性；
- setTextPosition() 数值单位为“半磅”（half-point），即 10 表示 5pt 位移；
- 并非所有 Word 客户端都能完美还原小型大写或阴影效果，建议测试目标环境。

classDiagram
    class XWPFRun {
        +setText(String)
        +setFontFamily(String)
        +setFontSize(int)
        +setBold(boolean)
        +setItalic(boolean)
        +setUnderline(UnderlinePatterns)
        +setColor(String)
        +setHighlightColor(HighlightColor)
        +setTextPosition(int)
        +setStrikeThrough(boolean)
    }

    class UnderlinePatterns {
        <<enumeration>>
        SINGLE
        DOUBLE
        DOTTED
        THICK
    }

    class HighlightColor {
        <<enumeration>>
        YELLOW
        GREEN
        CYAN
        MAGENTA
        BLUE
        RED
    }

    XWPFRun --> UnderlinePatterns : uses
    XWPFRun --> HighlightColor : uses

上图展示了 XWPFRun 类与其相关枚举类型的关联关系，体现了 Apache POI 对 OpenXML 规范的映射设计。

3.2 段落格式化：XWPFParagraph高级设置

如果说 XWPFRun 控制的是“字”的外观，那么 XWPFParagraph 则决定了“行”的布局。它负责管理段落级别的格式信息，包括对齐方式、缩进、行距、段前段后间距等，直接影响文档的整体排版结构与阅读体验。

3.2.1 对齐方式（左对齐、居中、右对齐、两端对齐）

段落对齐是文档中最常见的格式需求之一。XWPF 提供 setAlignment() 方法来设置段落对齐模式，接受 TableRowAlign 枚举类型。

XWPFParagraph alignPara = document.createParagraph();
alignPara.setAlignment(ParagraphAlignment.CENTER);

XWPFRun run = alignPara.createRun();
run.setText("这是一个居中的段落");

支持的对齐方式如下：

枚举值	效果	应用场景
LEFT	左对齐（默认）	正文段落
CENTER	居中对齐	标题、章节名
RIGHT	右对齐	页眉、日期、签名栏
BOTH	两端对齐	正式公文、出版物

✅ 最佳实践 ：对于正式文档，正文推荐使用 BOTH （两端对齐），以获得更整齐的左右边缘。

3.2.2 缩进控制（首行缩进、左右边距）

通过 setIndentationLeft() 、 setIndentationRight() 和 setIndentationFirstLine() 可以精确控制段落的缩进量。数值单位为 Twips （缇），1 英寸 = 1440 Twips，1 厘米 ≈ 567 Twips。

XWPFParagraph indentPara = document.createParagraph();
indentPara.setIndentationLeft(567);     // 左缩进 1cm
indentPara.setIndentationRight(283);    // 右缩进 0.5cm
indentPara.setIndentationFirstLine(567); // 首行缩进 1cm

XWPFRun run = indentPara.createRun();
run.setText("这是一个设置了复杂缩进的段落。首行缩进1厘米，左右分别缩进1cm和0.5cm。");

缩进单位换算参考表：

单位	换算关系	示例值
Twip	1/1440 英寸	567 ≈ 1cm
Point	1/72 英寸	72pt = 1in
Pixel	依赖 DPI	通常 96px = 1in

⚠️ 注意：Apache POI 不提供自动单位转换工具，开发者需自行计算 Twips 值。

3.2.3 行间距与段前段后间距的精确调整

良好的行间距能显著提升文档可读性。XWPF 支持通过 setSpacingAfter() , setSpacingBefore() 和 setSpacingLineRule() 设置段前、段后及行间距离。

XWPFParagraph spacingPara = document.createParagraph();

// 设置段前 12pt，段后 6pt
spacingPara.setSpacingBefore(240);   // 12pt * 20 = 240 twips
spacingPara.setSpacingAfter(120);    // 6pt * 20 = 120 twips

// 设置行间距为 1.5 倍（276 单位表示 1.5 行高）
spacingPara.setSpacingLine(276);
spacingPara.setSpacingLineRule(LineSpacingRule.AUTO);

XWPFRun run = spacingPara.createRun();
run.setText("这段文字具有较大的段前段后间距和1.5倍行距。");

行间距规则说明：

LineSpacingRule	含义	适用场景
AUTO	自动行距（基于字号）	默认值
EXACT	精确值（单位 twips）	固定排版
AT_LEAST	最小行高	防止文字挤压

💬 经验分享 ：
- 段前/段后间距单位为 twips（×20 = pt）；
- 行高若设为 EXACT ，建议设置为字号的 1.2~1.5 倍，避免截断；
- 使用 AT_LEAST 更安全，允许内容扩展而不溢出。

flowchart TD
    A[开始设置段落格式] --> B{选择对齐方式}
    B --> C[LEFT / CENTER / RIGHT / BOTH]
    C --> D[设置缩进]
    D --> E[左/右/首行缩进（twips）]
    E --> F[配置间距]
    F --> G[段前/段后/行距]
    G --> H[保存至文档]
    H --> I[结束]

流程图展示了段落格式化的典型操作路径，强调了单位转换与顺序执行的重要性。

3.3 样式复用与自定义样式定义

在实际项目中，若每次都要手动设置字体、颜色、缩进等属性，不仅效率低下且难以保证一致性。为此，XWPF 提供了 XWPFStyles 机制，允许开发者定义和复用样式模板，极大提升了开发效率与维护性。

3.3.1 利用XWPFStyles应用预设样式（如Heading1）

Word 内置了许多标准样式（如 Heading 1 , Title , Subtitle ），可通过名称直接引用：

XWPFStyles styles = document.getStyles();
XWPFParagraph heading = document.createParagraph();
heading.setStyle("Heading1");

XWPFRun run = heading.createRun();
run.setText("这是一个一级标题");

前提是模板文档中已存在该样式。也可通过 styles.addStyle() 注册新样式。

3.3.2 创建并注册自定义段落样式

若需创建全新样式（如“公司正文”、“法律条款”），可通过 CTStyle 手动定义：

CTStyle ctStyle = CTStyle.Factory.newInstance();
ctStyle.setStyleId("CustomBodyText");

STStyleType.Enum type = STStyleType.PARAGRAPH;
ctStyle.setType(type);

// 设置基于样式
CTString styleName = CTString.Factory.newInstance();
styleName.setVal("自定义正文");
ctStyle.setName(styleName);

// 设置段落属性
CTPPr ppr = CTPPr.Factory.newInstance();
ppr.setAlign(STJc.LEFT);
ppr.setInd(CTTrPtMeasure.Factory.newInstance());
ppr.getInd().setLeft(Long.valueOf(720)); // 0.5 inch
styles.getCTStyles().addStyle(ctStyle);

// 应用样式
XWPFParagraph customPara = document.createParagraph();
customPara.setStyle("CustomBodyText");

3.3.3 样式继承机制与优先级规则

XWPF 遵循 CSS 式的样式继承机制：
- 段落样式 → Run 样式 → 直接属性设置
- 后者优先级高于前者

即：

run.setBold(true); // 最高优先级
// 覆盖了即使样式中定义为非粗体的情况

层级	来源	优先级
1	直接属性设置（如 setBold() ）	最高
2	Run/Paragraph 样式定义	中等
3	默认文档样式	最低

🔁 设计建议 ：建立全局样式表 .dotx 模板，加载后复用，确保品牌一致性。

// 加载含样式的模板
try (FileInputStream fis = new FileInputStream("template.dotx")) {
    XWPFDocument doc = new XWPFDocument(fis);
    XWPFParagraph p = doc.createParagraph();
    p.setStyle("CompanyNameStyle");
}

综上所述， XWPFRun 与 XWPFParagraph 构成了 Apache POI 文档样式控制的两大支柱。通过对字体、颜色、段落格式的精细操控，结合样式复用机制，开发者能够构建出高度专业化、标准化的自动化文档输出系统。下一章将在此基础上引入表格结构，拓展复杂数据的组织能力。

4. 表格生成与格式化（XWPFTable应用）

在现代企业级文档自动化系统中，表格作为信息结构化展示的核心载体，广泛应用于报表、合同、技术文档等场景。Apache POI 的 XWPF 模块提供了对 .docx 格式中表格的全面支持，通过 XWPFTable 、 XWPFTableRow 和 XWPFTableCell 三个核心类构建出完整的表格对象模型。本章将深入探讨如何利用这些组件实现从零开始创建表格、动态管理行列结构、精确控制单元格内容样式，并进一步优化整体外观布局，以满足复杂业务场景下的排版需求。

4.1 表格创建与行列管理

4.1.1 初始化XWPFTable对象并指定列数

在 Apache POI 中， XWPFTable 是表示一个 Word 文档中表格的主类，它继承自 IBodyElement 接口，能够被添加到文档主体或节中。创建表格的第一步是通过 XWPFDocument 实例调用 createTable(rows, cols) 方法初始化一个具有固定行数和列数的表格对象。

XWPFDocument document = new XWPFDocument();
// 创建一个3行5列的空表格
XWPFTable table = document.createTable(3, 5);

该方法底层会自动构建对应数量的 XWPFTableRow 和 XWPFTableCell 对象，并建立父子关系链。值得注意的是，虽然指定了初始行数，但实际开发中更常见的是先创建单行（表头），然后通过程序逻辑动态追加后续数据行。

参数	类型	描述
rows	int	初始行数，必须大于0
cols	int	列数，用于确定每行的单元格数量

⚠️ 注意 ：若传入非法参数（如负值），将抛出 IllegalArgumentException 。此外， .docx 规范限制最大列数为63，超过此值可能导致兼容性问题。

使用 Mermaid 流程图展示表格初始化过程：

graph TD
    A[XWPFDocument] --> B[调用 createTable(rows, cols)]
    B --> C{验证参数合法性}
    C -->|合法| D[创建XWPFTable实例]
    D --> E[生成指定数量的XWPFTableRow]
    E --> F[为每一行创建XWPFTableCell]
    F --> G[建立DOM树结构]
    G --> H[返回table引用]
    C -->|非法| I[抛出IllegalArgumentException]

上述流程体现了 POI 内部对 OpenXML 结构的封装机制——每一个 XWPFTable 都对应一个 <w:tbl> XML 元素，其子元素包括 <w:tr> （行）和 <w:tc> （单元格）。这种设计使得开发者无需直接操作 XML，即可完成语义清晰的表格构造。

4.1.2 动态添加行与单元格数据填充

尽管可以通过 createTable 预设行数，但在大多数应用场景中（如导出数据库查询结果），表格行数往往是未知的，需在运行时逐行添加。为此， XWPFTable 提供了 createRow() 方法来扩展表格：

// 获取已有表格并添加新行
XWPFTableRow newRow = table.createRow();
newRow.getCell(0).setText("姓名");
newRow.getCell(1).setText("年龄");
newRow.getCell(2).setText("部门");

然而需要注意的是，首次调用 createRow() 实际上并不会增加“可见”行，而是复用最初由 createTable 创建的第一行。因此，正确做法通常是先清除默认行再重新构建：

// 清除默认生成的首行（可选）
while (table.getNumberOfRows() > 0) {
    table.removeRow(0);
}

// 手动添加表头行
XWPFTableRow headerRow = table.createRow();
for (int i = 0; i < 5; i++) {
    headerRow.getCell(i).setText("列标题 " + (i + 1));
}

对于数据填充，可通过嵌套循环遍历二维数据集：

List<List<String>> data = Arrays.asList(
    Arrays.asList("张三", "28", "研发部", "高级工程师", "2020-01-01"),
    Arrays.asList("李四", "32", "市场部", "项目经理", "2019-05-15")
);

for (List<String> rowData : data) {
    XWPFTableRow row = table.createRow();
    for (int i = 0; i < rowData.size(); i++) {
        row.getCell(i).setText(rowData.get(i));
    }
}

代码逻辑逐行解析：

1. List<List<String>> data 定义了一个模拟的数据源，代表多行记录。
2. 外层 for 循环迭代每一行数据。
3. table.createRow() 动态插入新行。
4. 内层 for 循环将每个字段值写入对应单元格。
5. row.getCell(i).setText(...) 设置文本内容，注意索引不能越界。

此模式适用于中小型数据集。当处理大量数据时，应结合流式处理策略避免内存溢出（详见第六章）。

4.1.3 合并单元格（横向与纵向合并）实现技巧

单元格合并是提升表格可读性的关键功能，在财务报表、组织架构图等场景中尤为常见。Apache POI 支持通过设置 GridSpan （横向合并）和 VMerge （纵向合并）属性实现跨列与跨行合并。

横向合并示例（跨列）

// 创建一行用于标题合并
XWPFTableRow titleRow = table.createRow();
XWPFTableCell cell = titleRow.getCell(0);

// 设置该单元格跨越5列
CTTcPr tcPr = cell.getCTTc().getTcPr();
if (tcPr == null) {
    tcPr = cell.getCTTc().addNewTcPr();
}
CTTblWidth gridSpan = tcPr.addNewGridSpan();
gridSpan.setW(BigInteger.valueOf(5));

cell.setText("员工基本信息汇总表");

参数说明：
- CTTcPr : 单元格属性容器，包含宽度、边框、对齐等配置。
- GridSpan.w : 表示该单元格所占的网格列数，类型为 BigInteger 。

纵向合并示例（跨行）

纵向合并需分别设置起始单元格为 restart ，其余为 continue ：

// 假设有3行，希望第一列的前两行垂直合并
XWPFTableRow row1 = table.getRow(1);
XWPFTableRow row2 = table.getRow(2);

XWPFTableCell cell1 = row1.getCell(0);
XWPFTableCell cell2 = row2.getCell(0);

// 起始单元格
CTVMerge vMerge1 = cell1.getCTTc().getTcPr().addNewVMerge();
vMerge1.setVal(STMerge.RESTART);

// 续接单元格
CTVMerge vMerge2 = cell2.getCTTc().getTcPr().addNewVMerge();
vMerge2.setVal(STMerge.CONTINUE);

合并类型	属性名称	控制方式	适用场景
横向合并	GridSpan	设置 w 值	表头标题
纵向合并	VMerge	RESTART / CONTINUE	分组统计

⚠️ 重要提示 ：手动合并后，被合并区域内的其他单元格仍存在，不可再赋值，否则会导致渲染错乱。建议在合并完成后统一设置内容。

4.2 单元格内容与样式控制

4.2.1 设置单元格内文本样式与段落布局

每个 XWPFTableCell 默认包含一个段落（ XWPFParagraph ），而段落中又可包含多个 XWPFRun 对象，形成“单元格 → 段落 → 文本片段”的三层结构。这意味着可以在同一单元格内混合不同字体样式：

XWPFTableCell cell = table.getRow(0).getCell(0);
cell.getText().clear(); // 清空默认段落

XWPFParagraph p = cell.addParagraph();
XWPFRun boldRun = p.createRun();
boldRun.setBold(true);
boldRun.setText("重要提示：");

XWPFRun normalRun = p.createRun();
normalRun.setText(" 此项需人工审核。");

该代码实现了富文本效果：前半部分加粗，后半部分正常显示。

表格：常用文本样式属性对照表

样式属性	方法名	示例值	是否支持
加粗	setBold(boolean)	true	✅
斜体	setItalic(boolean)	false	✅
下划线	setUnderline(UnderlinePatterns)	SINGLE	✅
字体大小	setFontSize(int)	12	✅
字体名称	setFontFamily(String)	“宋体”	✅
颜色	setColor(String)	“FF0000”	✅

通过组合 Run 可实现类似 HTML <span> 的局部样式控制，极大增强了表达能力。

4.2.2 背景颜色与边框线型的独立配置

设置单元格背景色需要访问底层 CT 对象：

XWPFTableCell cell = row.getCell(0);
CTShd ctShd = cell.getCTTc().getTcPr().addNewShd();
ctShd.setFill("D3D3D3"); // 灰色背景
ctShd.setColor("auto");
ctShd.setVal(STShd.CLEAR);

其中 fill="D3D3D3" 表示填充色 RGB 值，十六进制表示法。

边框则可通过 setBorderTop , setBorderBottom 等方法单独设置：

cell.setBorderTop(XWPFBorderType.SINGLE, 1, 0, "000000");
cell.setBorderLeft(XWPFBorderType.THICK, 3, 0, "000000");

参数含义如下：
- 第一参数：边框类型（SINGLE、THICK、DASH_DOT 等）
- 第二参数：线宽（单位：8ths of a point）
- 第三参数：间距（可忽略）
- 第四参数：颜色（HEX 格式）

4.2.3 自动换行与垂直对齐方式调整

控制文本换行与对齐有助于提升表格整洁度：

CTTcPr tcPr = cell.getCTTc().getTcPr();
if (tcPr == null) tcPr = cell.getCTTc().addNewTcPr();

// 启用自动换行
CTTextWrap textWrap = tcPr.addNewTextWrap();
textWrap.setVal(STTextWrap.fromString("wrap"));

// 设置垂直居中
CTVerticalJc vAlign = tcPr.addNewVAlign();
vAlign.setVal(STVerticalJc.CENTER);

Mermaid 图表示意：

classDiagram
    XWPFTableCell --> XWPFParagraph : 包含
    XWPFParagraph --> XWPFRun : 包含多个
    XWPFTableCell --> CTTcPr : 持有样式
    CTTcPr --> CTShd : 背景
    CTTcPr --> CTTextWrap : 换行
    CTTcPr --> CTVAlign : 垂直对齐

4.3 表格整体外观优化

4.3.1 表格宽度分配策略（固定/百分比）

可通过 setWidth() 和 setWidthType() 控制表格总宽：

table.setWidth("80%"); // 百分比宽度
table.setWidthType(TableWidthDistribution.AUTO);

或使用固定值（单位：twips，1 inch = 1440 twips）：

table.setWidth("9000"); // 约6.25英寸

列宽可通过 setCellMarginLeft 或直接修改 CTTcPr 中的 tcW 实现：

XWPFTableCell cell = row.getCell(0);
CTTcPr tcPr = cell.getCTTc().getTcPr();
CTTblWidth tcW = tcPr.addNewTcW();
tcW.setW(BigInteger.valueOf(2000)); // 设置宽度
tcW.setType(STTblWidth.DXA); // DXA 表示 twentieths of a point

4.3.2 表头重复显示（适用于跨页表格）

启用表头跨页重复的关键是标记第一行为“标题行”：

XWPFTableRow header = table.getRow(0);
header.getCtRow().addNewTrPr().addNewTblHeader();

这样当表格分页时，Word 将自动复制该行至新页面顶部。

4.3.3 边框隐藏与网格样式统一设置

批量设置无边框并恢复网格线：

table.setInsideHBorder(XWPFBorderType.NIL, 0, 0, null);
table.setInsideVBorder(XWPFBorderType.NIL, 0, 0, null);
table.setOutsideBorder(XWPFBorderType.SINGLE, 1, 0, "000000");

或统一为细线网格：

for (XWPFTableRow r : table.getRows()) {
    for (XWPFTableCell c : r.getTableCells()) {
        c.setBorderTop(XWPFBorderType.SINGLE, 1, 0, "000000");
        c.setBorderBottom(XWPFBorderType.SINGLE, 1, 0, "000000");
        c.setBorderLeft(XWPFBorderType.SINGLE, 1, 0, "000000");
        c.setBorderRight(XWPFBorderType.SINGLE, 1, 0, "000000");
    }
}

综上所述，通过对 XWPFTable 的精细化控制，不仅可以实现基础表格构建，还能完成高度定制化的专业排版需求，为自动化文档生成提供强大支撑。

5. 图片与图表插入技术（XWPFPictureData集成）

在自动化文档生成系统中，图像和图表的嵌入不仅是提升信息表达力的关键手段，更是构建专业级报告、技术白皮书或商业合同的重要组成部分。Apache POI 的 XWPF 模块通过 XWPFPictureData 类实现了对多种图像格式的支持，并提供了灵活的图文混排机制，使得开发者可以在 .docx 文档中精确控制图像的位置、尺寸以及与文本的交互方式。本章将深入剖析图像资源的加载流程、图片样式配置逻辑，以及如何结合外部绘图库实现动态图表的嵌入，从而为复杂文档场景提供完整的可视化支持。

5.1 图像资源的嵌入与定位

5.1.1 支持的图像格式（JPEG、PNG、EMF等）与限制

Apache POI 在 XWPF 中支持多种主流图像格式的嵌入，主要包括 JPEG、PNG、GIF、BMP 和 EMF（Enhanced Metafile），这些格式分别适用于不同的使用场景：

图像格式	MIME Type	特点	使用建议
JPEG	image/jpeg	高压缩比，适合照片类图像	报告中的实景图、产品照
PNG	image/png	无损压缩，支持透明通道	图标、流程图、带透明背景的图形
GIF	image/gif	支持动画，色彩有限	动态演示不推荐用于正式文档
BMP	image/bmp	未压缩，体积大	不推荐生产环境使用
EMF	image/emf	Windows 矢量图，缩放不失真	专业出版物、高分辨率打印

需要注意的是，虽然 POI 支持上述格式，但 .docx 文件本质上是基于 OpenXML 标准的 ZIP 包，所有图像都会被编码为二进制数据并存储于 word/media/ 目录下。因此，在实际应用中应优先选择压缩效率高且兼容性良好的格式，如 PNG 和 JPEG。

此外，存在以下限制：
- 文件大小 ：过大的图像可能导致内存溢出或文档打开缓慢。
- DPI 分辨率 ：Word 默认按 96 DPI 渲染图像，若需高清输出，应在插入后手动调整布局。
- 跨平台兼容性 ：EMF 是 Windows 特有格式，在非 Windows 系统上可能无法正确渲染。

5.1.2 将字节数组或文件流转换为XWPFPictureData

要将图像嵌入 .docx 文档，必须首先将其转化为 XWPFPictureData 对象。该过程通常包括读取图像输入流，并调用 Document#addPicture() 方法注册图片资源。

import org.apache.poi.xwpf.usermodel.*;
import java.io.FileInputStream;
import java.io.IOException;

public class ImageEmbedder {
    public static void embedImage(XWPFDocument document, String imagePath, int pictureType) throws IOException {
        try (FileInputStream is = new FileInputStream(imagePath)) {
            byte[] bytes = is.readAllBytes();
            // 将图像数据添加到文档中，返回其在文档中的索引
            int pictureIndex = document.addPictureData(bytes, pictureType);
            // 获取当前段落或创建新段落
            XWPFParagraph paragraph = document.createParagraph();
            XWPFRun run = paragraph.createRun();

            // 插入图片
            run.addPicture(document.getPackagePart(), pictureType, imagePath, 
                           Units.toEMU(400), Units.toEMU(300)); // 宽400px, 高300px
        }
    }
}

代码逻辑逐行解读：

1. FileInputStream is = new FileInputStream(imagePath)
   打开本地图像文件的输入流，准备读取原始字节。

2. byte[] bytes = is.readAllBytes()
   将整个图像读入内存字节数组。注意：对于大文件，此操作可能引发 OutOfMemoryError ，后续章节会介绍流式处理优化方案。

3. document.addPictureData(bytes, pictureType)
   调用文档对象方法将图像数据注册为一个内嵌资源，返回唯一索引 pictureIndex ，用于后续引用。

4. document.getPackagePart()
   获取底层 OPCPackage 的 PackagePart，这是 OpenXML 文档结构的一部分，表示当前文档容器。

5. Units.toEMU(400)
   Apache POI 使用 English Metric Units (EMU) 表示尺寸（1 inch = 914400 EMUs）。此处将像素转换为 EMU 单位以适配 Word 布局引擎。

6. run.addPicture(...)
   在指定 Run 中插入图像，形成图文混排效果。

⚠️ 参数说明： pictureType 必须匹配实际图像类型，例如 XWPFDocument.PICTURE_TYPE_JPEG 或 PICTURE_TYPE_PNG ，否则会导致文档损坏。

5.1.3 在段落中插入图片并控制尺寸与位置

图像在 Word 文档中的呈现依赖于其所在的 XWPFRun 和父级 XWPFParagraph 。默认情况下，图像以“内联”（inline）形式插入，即作为文本流的一部分进行排列。

可以通过设置运行属性来微调图像位置：

XWPFRun run = paragraph.createRun();
run.setText("图1：系统架构示意图");
run.addCarriageReturn(); // 换行

// 设置图片居中对齐
paragraph.setAlignment(ParagraphAlignment.CENTER);

run = paragraph.createRun();
run.addPicture(
    document.getPackagePart(),
    XWPFDocument.PICTURE_TYPE_PNG,
    "arch-diagram.png",
    Units.toEMU(500), // 宽度（EMU）
    Units.toEMU(350)  // 高度（EMU）
);

mermaid 流程图：图像插入流程

graph TD
    A[开始] --> B{图像源是否存在?}
    B -- 否 --> C[抛出 FileNotFoundException]
    B -- 是 --> D[读取图像为字节数组]
    D --> E[调用 addPictureData 注册图像]
    E --> F[获取 PackagePart 引用]
    F --> G[创建段落与Run]
    G --> H[调用 addPicture 插入图像]
    H --> I[设置尺寸与对齐方式]
    I --> J[结束]

该流程清晰展示了从图像读取到最终渲染的完整链路，强调了资源注册与布局分离的设计思想。

5.2 图片样式与环绕方式设置

5.2.1 图文混排模式（inline vs floating）选择

Apache POI 提供两种主要图像布局模式：

• Inline（内联） ：图像作为字符插入文本流中，随段落移动，不能自由定位。
• Floating（浮动） ：图像脱离文本流，可设置绝对位置、环绕方式和层级关系。

目前 XWPF 原生 API 主要支持 Inline 模式。要实现 Floating 效果，需直接操作底层 OpenXML XML 结构，借助 CTDrawing 和 CTAnchor 元素。

import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;
import java.math.BigInteger;

private void addFloatingImage(XWPFDocument doc, XWPFParagraph paragraph, byte[] imageData) {
    // 创建 Drawing 容器
    CTDrawing drawing = paragraph.getCTP().addNewR().addNewDrawing();
    // 创建锚点（相对于页边距定位）
    CTAnchor anchor = drawing.addNewAnchor();
    anchor.setSimplePos(false);
    anchor.setRelativeHeight(BigInteger.valueOf(25165824)); // 层级Z-order
    anchor.setBehindDoc(false); // 是否置于文字下方
    anchor.setLockWithAspectLock(true); // 锁定宽高比

    // 设置位置（单位：EMU）
    CTPoint2D offset = anchor.addNewPositionH().addNewAlign();
    offset.setVal(STAlignType.CENTER); // 水平居中
    anchor.addNewPositionV().addNewAlign().setVal(STAlignType.CENTER);

    // 图像宽度高度（EMU）
    anchor.setExtent(CTSSTUnit.Factory.newInstance());
    anchor.getExtent().setCx(Units.toEMU(400));
    anchor.getExtent().setCy(Units.toEMU(300));

    // 创建图像内容
    CTGraphicalObjectFrame graphicFrame = anchor.addNewGraphic().addNewGraphicData();
    graphicFrame.setUri("http://schemas.openxmlformats.org/drawingml/2006/picture");

    CTPicture ctPic = graphicFrame.addNewPic();
    CTNonVisualPictureProperties nvProps = ctPic.addNewNvPicPr();
    nvProps.addNewCNvPr().setId(1);
    nvProps.getCNvPr().setName("Picture 1");

    // 设置图像数据引用
    CTRelativeFromH posH = anchor.addNewPositionH();
    posH.setRelativeFrom(STRelativeFromH.MARGIN);
    posH.setAlign(STAlignH.CENTER);

    CTPositiveSize2D extent = ctPic.addNewSpPr().addNewXfrm().addNewExt();
    extent.setCx(Units.toEMU(400));
    extent.setCy(Units.toEMU(300));

    // 添加 Blip（图像位图引用）
    CTBlipFillProperties blipFill = ctPic.addNewBlipFill();
    CTBlip blib = blipFill.addNewBlip();
    String relationshipId = doc.addPictureData(imageData, XWPFDocument.PICTURE_TYPE_PNG);
    blib.setEmbed(relationshipId);
}

表格：Inline 与 Floating 模式的对比

特性	Inline 模式	Floating 模式
实现难度	简单，原生支持	复杂，需操作 CT 对象
定位能力	固定在段落流中	可设定坐标、对齐方式
环绕支持	仅基本换行	支持四周型、紧密型等
编辑友好性	易于维护	修改困难，易出错
推荐用途	内容插图、小图标	精确定位图表、封面图

5.2.2 设置图片与文字的环绕类型（四周型、紧密型等）

尽管 XWPF 不直接暴露环绕设置接口，但可通过修改 anchor 中的 wrapSquare 元素实现：

CTWrapSquare wrap = anchor.addNewWrapSquare();
wrap.setWrapText(STWrapText.BOTH_SIDES); // BOTH_SIDES / LEFT / RIGHT

环绕类型说明如下：

• BOTH_SIDES ：文字环绕图像两侧（四周型）
• LEFT ：仅右侧环绕
• RIGHT ：仅左侧环绕
• LARGEST ：根据图像形状自动判断

这种底层操作允许开发者模拟 Microsoft Word 中的高级排版行为，但需要熟悉 OpenXML Schema 结构。

5.2.3 图片标题自动生成与编号管理

为了增强文档的专业性，常需为图像添加自动编号标题，如“图1：XXX”。

private int figureCounter = 1;

private void insertLabeledImage(XWPFDocument doc, XWPFParagraph para, String imagePath, String caption) throws IOException {
    byte[] imgData = Files.readAllBytes(Paths.get(imagePath));
    int picType = determinePictureType(imagePath);

    // 插入图像
    XWPFRun run = para.createRun();
    run.addCarriageReturn();
    run.setText(String.format("图%d：%s", figureCounter++, caption));
    run.addCarriageReturn();

    run = para.createRun();
    run.addPicture(
        doc.getPackagePart(),
        picType,
        imagePath,
        Units.toEMU(450),
        Units.toEMU(300)
    );
    run.addCarriageReturn();
}

此方法实现了简单的顺序编号机制。更高级的做法是结合 XWPFStyles 定义“题注”样式，并利用 numId 实现多级列表编号。

5.3 图表与复杂图形的间接集成方案

5.3.1 使用Apache POI插入已生成的图表图像

由于 Apache POI 当前版本（5.2.4）尚不支持原生 Chart 对象（如 <c:chart> ）的创建，最实用的方法是先用其他库生成图表图像，再以静态图片形式嵌入。

典型流程如下：

1. 使用 JFreeChart、XChart 或 Plotly Java 生成统计图并导出为 PNG。
2. 将图像写入临时文件或内存流。
3. 调用 XWPFRun#addPicture 插入文档。

// 示例：生成柱状图并插入
JFreeChart chart = ChartFactory.createBarChart(
    "销售额统计", "月份", "金额",
    createDataset(), PlotOrientation.VERTICAL, true, true, false
);

BufferedImage bufferedImage = chart.createBufferedImage(600, 400);
ByteArrayOutputStream baos = new ByteArrayOutputStream();
ImageIO.write(bufferedImage, "png", baos);

// 插入到文档
int idx = document.addPictureData(baos.toByteArray(), Document.PICTURE_TYPE_PNG);
XWPFParagraph p = document.createParagraph();
XWPFRun r = p.createRun();
r.addPicture(document.getPackagePart(), XWPFDocument.PICTURE_TYPE_PNG, "chart.png", 
             Units.toEMU(500), Units.toEMU(350));

这种方式虽失去交互性和动态更新能力，但在大多数报表场景中已足够使用。

5.3.2 结合JFreeChart等库生成统计图并嵌入文档

下面是一个完整的 JFreeChart + POI 集成示例：

private CategoryDataset createDataset() {
    DefaultCategoryDataset dataset = new DefaultCategoryDataset();
    dataset.addValue(120, "Q1", "北京");
    dataset.addValue(150, "Q1", "上海");
    dataset.addValue(130, "Q1", "广州");
    return dataset;
}

private void generateChartAndInsert(XWPFDocument doc) throws IOException {
    JFreeChart chart = ChartFactory.createBarChart(
        "区域销售对比", "城市", "销售额（万元）",
        createDataset(),
        PlotOrientation.VERTICAL,
        true, true, false
    );

    // 自定义样式
    chart.getTitle().setFont(new Font("SimHei", Font.BOLD, 16));
    CategoryPlot plot = (CategoryPlot) chart.getPlot();
    plot.getDomainAxis().setLabelFont(new Font("SimSun", Font.PLAIN, 12));
    plot.getRangeAxis().setLabelFont(new Font("SimSun", Font.PLAIN, 12));

    BufferedImage img = chart.createBufferedImage(700, 400);
    ByteArrayOutputStream os = new ByteArrayOutputStream();
    ImageIO.write(img, "png", os);

    XWPFParagraph p = doc.insertNewParagraph(doc.getDocument().getCTBody().addNewP());
    XWPFRun r = p.createRun();
    r.addPicture(
        new ByteArrayInputStream(os.toByteArray()),
        XWPFDocument.PICTURE_TYPE_PNG,
        "sales-chart.png",
        Units.toEMU(600),
        Units.toEMU(400)
    );
}

✅ 优势：完全可控的视觉设计；支持中文渲染；可复用于 PDF、Web 输出。

❌ 缺陷：图表为静态图像，无法在 Word 中双击编辑。

5.3.3 图表更新机制与动态数据绑定思路

尽管无法实现真正的“动态图表”，但仍可通过模板化策略模拟数据驱动更新：

1. 预定义图像占位符 ：在模板文档中标记图像区域（如 ${chart:sales} ）。
2. 运行时替换 ：识别标记，生成对应图表图像，替换原图。
3. 缓存机制 ：对高频图表进行结果缓存，避免重复计算。

Map<String, BufferedImage> chartCache = new ConcurrentHashMap<>();

String placeholder = "${chart:revenue-q3}";
if (placeholder.startsWith("${chart:")) {
    String key = extractKey(placeholder); // revenue-q3
    BufferedImage chartImg = chartCache.computeIfAbsent(key, k -> generateRevenueChart(k));
    byte[] pngData = renderToByteArray(chartImg, "png");
    replacePlaceholderWithImage(document, placeholder, pngData);
}

未来随着 POI 社区对 XWPFChart 的逐步支持，有望实现真正的 OpenXML Chart 对象插入，届时将能生成可在 Word 中编辑的图表。

6. 自动化应用场景实战：报表生成、合同定制、邮件合并

6.1 基于模板的动态数据填充与占位符替换

在企业级文档自动化场景中，使用预定义的 .docx 模板进行动态内容填充是一种高效且可维护的方式。Apache POI 提供了对段落和表格中文本内容的精细控制能力，使得开发者可以实现基于占位符（如 ${name} ）的智能替换机制。

6.1.1 定义占位符语法与正则匹配规则

推荐采用 ${key} 的语法格式作为占位符标识，便于通过正则表达式精准识别。以下为通用匹配逻辑：

import java.util.regex.Pattern;

public class PlaceholderMatcher {
    // 匹配 ${xxx} 格式的占位符
    private static final Pattern PLACEHOLDER_PATTERN = 
        Pattern.compile("\\$\\{([a-zA-Z0-9._]+)}");

    public static Pattern getPattern() {
        return PLACEHOLDER_PATTERN;
    }
}

该正则表达式会捕获 ${} 内部的字段名（如 user.name ），支持嵌套属性路径。

6.1.2 遍历段落与表格实现全局替换

XWPF 中需分别处理段落（XWPFParagraph）和表格（XWPFTable）。以下是统一遍历并替换的核心方法：

import org.apache.poi.xwpf.usermodel.*;

import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;

public void replacePlaceholders(XWPFDocument doc, Map<String, String> data) {
    // 替换普通段落
    for (XWPFParagraph p : doc.getParagraphs()) {
        replaceInParagraph(p, data);
    }

    // 替换所有表格中的段落
    for (XWPFTable table : doc.getTables()) {
        for (XWPFTableRow row : table.getRows()) {
            for (XWPFTableCell cell : row.getTableCells()) {
                for (XWPFParagraph p : cell.getParagraphs()) {
                    replaceInParagraph(p, data);
                }
            }
        }
    }
}

private void replaceInParagraph(XWPFParagraph paragraph, Map<String, String> data) {
    String text = paragraph.getText();
    if (text == null) return;

    Matcher matcher = PlaceholderMatcher.getPattern().matcher(text);
    StringBuffer sb = new StringBuffer();

    boolean hasReplacement = false;
    while (matcher.find()) {
        String key = matcher.group(1);
        String value = data.getOrDefault(key, "N/A"); // 默认值防空
        matcher.appendReplacement(sb, Matcher.quoteReplacement(value));
        hasReplacement = true;
    }
    matcher.appendTail(sb);

    if (hasReplacement) {
        // 清除原有 runs 并添加新文本
        List<XWPFRun> runs = paragraph.getRuns();
        if (!runs.isEmpty()) {
            XWPFRun firstRun = runs.get(0);
            firstRun.setText(sb.toString(), 0);
            for (int i = 1; i < runs.size(); i++) {
                paragraph.removeRun(i);
            }
        } else {
            paragraph.createRun().setText(sb.toString());
        }
    }
}

执行逻辑说明 ：
- 使用 StringBuffer 和 Matcher.appendReplacement() 实现安全字符串拼接；
- 替换后保留原第一个 Run 的样式（字体、颜色等），避免格式丢失；
- 若原段落无 Run，则创建新的 Run 插入。

6.1.3 处理复杂数据结构（列表、嵌套对象）的渲染逻辑

当模板中需要循环插入表格行或重复段落时，可引入特殊标记（如 <!-- LOOP:userList -->...<!-- END_LOOP --> ）结合 AST 解析实现结构化渲染。

示例：JSON 数据模型

{
  "reportTitle": "月度销售报告",
  "generatedDate": "2025-04-05",
  "salesTeam": [
    {"name": "张三", "region": "华东", "quota": 800000},
    {"name": "李四", "region": "华北", "quota": 750000},
    {"name": "王五", "region": "华南", "quota": 920000}
  ]
}

可通过递归遍历模板段落，在检测到 LOOP 指令时动态克隆行并填充每项数据。

6.2 批量文档生成中的流式处理与内存优化策略

6.2.1 分批生成避免 OutOfMemoryError

传统 XWPFDocument 将整个文档加载至内存，面对数千份合同或报表时极易引发 OutOfMemoryError 。建议按批次处理，例如每批 50 份文档，处理完成后释放资源：

for (int i = 0; i < dataList.size(); i += 50) {
    List<DataEntry> batch = dataList.subList(i, Math.min(i + 50, dataList.size()));
    processBatch(batch);
    System.gc(); // 可选触发垃圾回收
}

6.2.2 使用 SXWPFStreaming 库进行大文档支持

SXWPFStreaming 是一个扩展库，提供类似 SXSSF 的流式写入能力。其核心思想是延迟写入、分块输出：

特性	XWPFDocument	SXWPFStreaming
内存占用	高（全载入）	低（流式）
最大文档大小	~100页以内	数千页
支持模板修改	是	是（受限）
并发写入	否	否
Maven坐标	poi-ooxml	com.github.opensagres:xdocreport

使用示例（伪代码）：

InputStream templateStream = new FileInputStream("template.docx");
XDocReport report = XDocReportRegistry.getRegistry().loadReport(templateStream, TemplateEngineKind.Freemarker);
OutputStream out = new FileOutputStream("output_report.docx");
Context context = report.createContext();
context.put("data", complexDataModel);
report.process(context, out);

6.2.3 文件分片与异步导出机制设计

对于超大规模任务（如10万份保单），应设计如下架构：

graph TD
    A[用户请求导出] --> B{是否批量?}
    B -->|是| C[拆分为子任务]
    C --> D[放入消息队列 RabbitMQ/Kafka]
    D --> E[消费者集群并行处理]
    E --> F[生成文档并上传OSS/S3]
    F --> G[发送完成通知邮件]
    B -->|否| H[同步生成返回流]

此方案实现了解耦、容错与横向扩展能力。

本文还有配套的精品资源，点击获取

简介：在IT领域，自动生成排版规范的Word文档广泛应用于数据报告、自动化办公和批量文本处理。通过Java语言结合Apache POI等工具库，开发者可实现对.docx文件的读写与样式控制，支持字体、段落、表格、图片、页眉页脚等元素的精确排版，并能通过模板机制动态填充数据，完成高效自动化导出。该技术已在金融报表、合同生成、邮件合并等场景中发挥重要作用。本文介绍完整的Word文档生成流程，涵盖核心API使用、页面元素操作、性能优化及异常处理，帮助开发者构建稳定高效的文档自动化系统。

本文还有配套的精品资源，点击获取