为什么要在 Java 中生成 Word 文档？

在企业日常运营里报表导出、合同批量生成以及技术报告编写常常需要动态输出 Word 文件。传统手工操作既费时又易出错，而在后端使用 Java 自动化完成这一步骤，不仅Neng大幅提升效率，还Neng保证格式统一。接下来我将带你从零开始，用一份清晰的代码实现完整的 Word 文档。

先别急着敲代码，先确保你的 IDE Neng够访问 Maven 仓库，并且 JDK Yi经安装完毕。Spire.Doc for Java 是一款功Neng齐全且不依赖本地 Office 的第三方组件，下面先把它加进项目。

 
   
     com.e-iceblue
     e‑iceblue
     https://repo.e-iceblue.cn/repository/maven-public/
   
 
 
   
     e‑iceblue
     spire.doc
     x.x.x    // 替换为Zui新版号
   
 

Ru果你位于国内网络，Ke以考虑配置代理或使用阿里云镜像，以免下载慢。

让我们打开一个空白文档，然后插入一个节。节是 Word 页面布局的基本单元，包含页眉页脚、边距等信息。

import com.spire.doc.* ;
import com.spire.doc.documents.* ;
import com.spire.doc.fields.DocPicture ;
import java.awt.* ;
public class CreateWordDemo {
    public static void main {
        // ① 创建 Document 实例
        Document doc = new Document ;
        // ② 新增一个节
        Section sec = doc.addSection ;
        // ③ 设置页面边距
        sec.getPageSetup.getMargins.setAll ;
        // … 接下来继续补充内容 …
    }
}

这里我们使用了单位转换工具 SpireDocUtils.CM_TO_POINT，把厘米转成点，geng符合 Word 的内部度量标准。

典型的报告开头会有一个大标题和作者/时间信息。我们把它们放在同一节中，但分别占据不同的段落。

// 主标题
Paragraph titlePara = sec.addParagraph ;
titlePara.getFormat.setHorizontalAlignment ;
TextRange titleText = titlePara.appendText ;
titleText.getCharacterFormat.setBold ;
titleText.getCharacterFormat.setFontName ;
titleText.getCharacterFormat.setFontSize ;      // 字号
// 作者段落
Paragraph authorPara = sec.addParagraph ;
authorPara.getFormat.setHorizontalAlignment ;
TextRange authorText = authorPara.appendText) ;
authorText.getCharacterFormat.setItalic ;
authorText.getCharacterFormat.setFontSize ;
authorText.getCharacterFormat.setColor ;
// 空行作为间距
sec.addParagraph ;

你会发现，每一次设置dou对应了“字符格式”或“段落格式”，这正是 Spire.Doc 把 Word 内部结构映射到 Java 对象的方式。

中文排版强调首行缩进，而正文往往包含多句描述。下面演示如何一次性插入整段文字，并让首行自动缩进。

// 正文段落
Paragraph bodyPara = sec.addParagraph ;
// 首行缩进为两个字符宽度
bodyPara.getFormat.setFirstLineIndent ;  
String bodyTxt =
    "本文演示了使用 Java 第三方组件生成 Word 文档的基本流程。" +
    "此方法不依赖本地 Office 软件，可在 Linux 或无 GUI 环境下直接运行。" +
    "随后我们会加入图片和表格，让报告geng具可视化效果。" ;
bodyPara.appendText ; 

Ru果你想在报告中展示某张截图或图标，只需调用 appendPicture 即可。但记得给图片设置宽高，否则可Neng被拉伸或裁剪。

// 图片段落
Paragraph imgPara = sec.addParagraph ;
imgPara.getFormat.setHorizontalAlignment ;
String imgPath = "/tmp/sample_image.png" ;          // 本地文件路径，请自行替换
DocPicture pic = imgPara.appendPicture ;   // 插入图片
// 缩放比例
pic.setWidth ;
// 高度Ke以自动保持比例，Ru果需要手动指定：
pic.setHeight) ;                   // 保持原比例即可 

温馨提示：  务必检查文件路径是否正确；否则程序会抛出 FileNotFoundException。

表格是展示结构化数据Zui直观的方法。下面先建一个三列两行的样例，然后再填充具体内容。

// 表格标题
Paragraph tblTitle = sec.addParagraph ;
tblTitle.appendText .getCharacterFormat
       .setBold
       .setFontSize
       .getColor
       .apply;
// 创建表格
Table tbl = sec.addTable;                 // true 表示有表头
tbl.resetCells;                          // 行数+1 , 列数
// 设置整体宽度为页面宽度减去左右边距
double pageWidthPts =
    doc.sections.firstOrDefault?.pageSetup?.paperSize?.width ?? 
    (doc.sections.pageSetup.paperSize.width - 
         doc.sections.pageSetup.margins.left - 
         doc.sections.pageSetup.margins.right);
tbl.setWidth;
tbl.getTableFormat
   .setCollapseBorders
   .getGridLines
   .getItems
   .forEach);
// 填写表头
String headers = {"模块名称", "进度", "负责人"} ;
TableRow headerRow = tbl.rows.firstOrDefault;
for;i++){
    Cell cell=headerRow.cells;
    cell.clear;                               // 清除默认空白段落
    Paragraph p=cell.addParagraph;
    p.appendText .
      getCharacterFormat
      .setBold
      .getColor
      .apply;
    cell.setCellBackgroundColor;
}
// 填写数据行
String data={
 {"需求分析","Yi完成%","张三"},
 {"后端开发","进行中%","李四"},
 {"前端设计","待开始%","王五"}};
for;r++){
 TableRow row=tbl.rows;
 for;c++){
     Cell cell=row.cells;
     cell.clear;
     cell.addParagraph
         .appendText
         .getCharacterFormat
         .getColor
         .apply;
 }
}

注意：  addTable 会自动为每个单元格创建空白段落，所以在写入文字之前Zui好先调用 clear.

Word 文档完成后需要持久化到磁盘，同时释放占用内存，避免泄漏。下面给出完整实现：

// 输出路径，可自定义目录结构
String outputDir ="output";
java.nio.file.Files.createDirectories);
String outFile ="created_demo.docx";
String fullPath=outputDir+"/"+outFile;
try{
 doc.saveToFile;
 System.out.println;
}catch{
 e.printStackTrace;
}finally{
 if{doc.dispose;}
}

环境准备：  Maven 仓库地址可Neng受地区限制，建议提前测试下载速度；若网络慢可用国内镜像加速。

代码风格：  不要过分追求模板式命名，适当加入业务语义Neng提升可读性，例如 section 为 reportSec 等；同时保持代码块之间有足够空白，让人阅读时不会出现视觉拥挤感。

性Neng考量：  大量数据渲染时Ke以考虑批量填充而不是逐个循环；Ru果只需要纯文本，可直接使用 Apache POI 的 XWPFDocument，这样体积geng轻，但功Neng略逊色于 Spire.Doc 的高级特性。

跨平台部署：  因为不依赖本地 Office，你Ke以把整个 jar 包打包成 Docker 镜像，在任何 Linux 环境下直接运行，无需额外安装 Office 或 LibreOffice 等组件。

错误处理：  生产环境请务必捕获 IOException 与 UnsupportedOperationException，并给出友好的日志提示，以免因路径权限导致程序异常终止。

未来 ：  Ru果需要合并多份模板或者根据用户输入动态调整布局，Ke以封装成工具类，例如 DocBuilder，通过链式调用快速拼装完整文档结构。