Apache POI for Java：完整指南与示例

1. 什么是 Apache POI，为什么需要它？

Apache POI（Poor Obfuscation Implementation）是一个用 Java 编写的强大开源库，用于创建、读取和修改 Microsoft Office 格式的文件（Excel、Word、PowerPoint、Outlook）。它允许开发人员以编程方式管理文档，而无需安装 Microsoft Office 套件。该库提供了两个主要的 API：HSSF（Horrible Spreadsheet Format）用于处理 .xls 格式（Excel 97-2003）的文件，以及 XSSF（XML Spreadsheet Format）用于处理现代 .xlsx 格式（Excel 2007+）的文件。对于 Word 文件，使用类似的组件：HWPF（用于 .doc）和 XWPF（用于 .docx）。

为什么需要它？在现代开发中，经常需要自动化处理办公文档：生成报告、从表格中导入数据、创建合同模板或生成复杂的分析摘要。Apache POI 解决了这些问题，为 Java 开发人员提供了对文档结构的完全控制：从 Excel 中的单元格格式化和创建图表，到 Word 中的表格、图像和样式处理。

该库由 Apache 软件基金会社区积极维护，拥有丰富的文档，并用于大型企业项目。它兼容 Java 8 及以上版本，使其成为大多数现代 Java 应用程序（包括 Web 服务、桌面应用程序和数据处理系统）的通用工具。

2. 安装

Apache POI 通过 Maven 中央仓库分发。要将其添加到项目中，需要在 pom.xml（对于 Maven）或 build.gradle（对于 Gradle）文件中添加依赖项。

Maven

<!-- 用于处理 Excel (.xls 和 .xlsx) 的主要依赖 -->\n<dependency>\n    <groupId>org.apache.poi</groupId>\n    <artifactId>poi-ooxml</artifactId>\n    <version>5.3.0</version>\n</dependency>\n\n<!-- 用于处理 Word 文档 (.doc 和 .docx) -->\n<dependency>\n    <groupId>org.apache.poi</groupId>\n    <artifactId>poi-scratchpad</artifactId>\n    <version>5.3.0</version>\n</dependency>

Gradle

implementation 'org.apache.poi:poi-ooxml:5.3.0'\nimplementation 'org.apache.poi:poi-scratchpad:5.3.0'

重要提示： 版本 5.3.0 在撰写本文时是最新的。建议在 Maven Repository 上检查最新版本。另请注意，poi-ooxml 已经包含了 poi（基础模块）和 poi-ooxml-lite（用于处理 OOXML 格式）。

3. 快速入门：最小工作示例

让我们创建一个简单的 Excel 文件，其中包含一行数据，并将其写入磁盘。

import org.apache.poi.ss.usermodel.*;\nimport org.apache.poi.xssf.usermodel.XSSFWorkbook;\n\nimport java.io.FileOutputStream;\nimport java.io.IOException;\n\npublic class QuickStart {\n    public static void main(String[] args) {\n        // 为 .xlsx 格式创建一个新的工作簿 (Workbook)\n        try (Workbook workbook = new XSSFWorkbook()) {\n            // 创建一个名为 "数据" 的工作表\n            Sheet sheet = workbook.createSheet("数据");\n\n            // 创建一行（索引 0 为第一行）\n            Row row = sheet.createRow(0);\n\n            // 在 A 列（索引 0）创建一个单元格\n            Cell cell = row.createCell(0);\n            cell.setCellValue("Hello, Apache POI!");\n\n            // 在 B 列（索引 1）创建一个包含数字的单元格