# ExcelToWord

**Repository Path**: G2S/excel-to-word

## Basic Information

- **Project Name**: ExcelToWord
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-07-30
- **Last Updated**: 2024-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, POI, poi-tl

## README

# README

## 目录

- [English Version](#english-version)
- [中文版本](#中文版本)

## English Version

### Overview

This Java application reads data from an Excel file, processes it, and populates a DOCX template with the extracted data. The resulting DOCX files are saved to a specified output location. The application utilizes the Apache POI library for handling Excel and DOCX files, and the Apache Commons CLI library for command-line option parsing.

### Prerequisites

Before running the application, ensure you have the following installed:

- Java Development Kit (JDK) 8 or higher
- Apache Maven (for managing dependencies)

### Dependencies

The following libraries are required:

- Apache POI
- Apache Commons CLI
- POI-TL (for DOCX template processing)

These dependencies are specified in the `pom.xml` file if you are using Maven.

### Compilation and Packaging

To compile and package the application using Maven, run:

```sh
mvn clean package
```

This command generates a `jar` file in the `target` directory.

### Usage

The application accepts three command-line arguments:

1. `-i` or `--input` : Path to the input Excel file
2. `-t` or `--template` : Path to the DOCX template file
3. `-o` or `--output` : Path to the output DOCX file

#### Example Command

```sh
java -jar target/your-jar-file.jar -i input.xlsx -t template.docx -o output.docx
```

### Detailed Workflow

1. **Command-Line Parsing**:
    - The `main` method defines and parses command-line options using Apache Commons CLI.
    - Required options: `input` (Excel file path), `template` (DOCX template path), `output` (output DOCX file path).

2. **Reading Excel Data**:
    - The `runExcelData` method reads the Excel file using Apache POI.
    - The first row of the Excel sheet is assumed to contain headers.
    - Each subsequent row is processed, and its data is stored in a map where keys are headers and values are cell data.

3. **Processing Each Row**:
    - For each row of data, the `processRowData` method:
        - Compiles the DOCX template with the row data using POI-TL.
        - Creates or appends content to the output DOCX file.
        - Copies paragraphs and tables from the template to the output document.

### Error Handling

The application handles the following exceptions:

- `ParseException` : Thrown if command-line arguments are invalid.
- `IOException` : Thrown during file read/write operations.
- `RuntimeException` : Thrown if any unexpected error occurs during document processing.

In case of errors, appropriate messages are printed to the console.

### Example

Given an Excel file `data.xlsx` with the following content:

| Name | Age | City    |
|------|-----|---------|
| John | 30  | New York|
| Jane | 25  | London  |

And a DOCX template `template.docx` with placeholders like `{{Name}}`, `{{Age}}`, and `{{City}}`, running the command:

```sh
java -jar target/your-jar-file.jar -i data.xlsx -t template.docx -o output.docx
```

Would generate an `output.docx` file populated with the data from `data.xlsx`.

### Conclusion

This application automates the process of reading data from an Excel file and generating DOCX documents based on a template, making it useful for generating reports, letters, or any other document that requires template-based data insertion.

For further customization and enhancement, refer to the official documentation of Apache POI, Apache Commons CLI, and POI-TL libraries.

[中文版本](#中文版本)

## 中文版本

### 概述

这个Java应用程序从Excel文件读取数据，处理后将其填充到DOCX模板中，并将生成的DOCX文件保存到指定的输出位置。该应用程序使用Apache POI库处理Excel和DOCX文件，并使用Apache Commons CLI库进行命令行选项解析。

### 前提条件

在运行应用程序之前，请确保已安装以下软件：

- Java开发工具包（JDK）8或更高版本
- Apache Maven（用于管理依赖项）

### 依赖项

该应用程序需要以下库：

- Apache POI
- Apache Commons CLI
- POI-TL（用于处理DOCX模板）

如果使用Maven，这些依赖项在`pom.xml`文件中指定。

### 编译和打包

使用Maven编译和打包应用程序，运行以下命令：

```sh
mvn clean package
```

该命令将在`target`目录中生成一个`jar`文件。

### 使用方法

该应用程序接受三个命令行参数：

1. `-i` 或 `--input`：输入Excel文件的路径
2. `-t` 或 `--template`：DOCX模板文件的路径
3. `-o` 或 `--output`：输出DOCX文件的路径

#### 示例命令

```sh
java -jar target/your-jar-file.jar -i input.xlsx -t template.docx -o output.docx
```

### 详细工作流程

1. **命令行解析**：
    - `main`方法使用Apache Commons CLI定义和解析命令行选项。
    - 必需选项：`input`（Excel文件路径）、`template`（DOCX模板路径）、`output`（输出DOCX文件路径）。

2. **读取Excel数据**：
    - `runExcelData`方法使用Apache POI读取Excel文件。
    - 假定Excel表的第一行包含标题。
    - 处理每一行数据，将其存储在一个映射中，其中键是标题，值是单元格数据。

3. **处理每一行**：
    - 对于每一行数据，`processRowData`方法：
        - 使用POI-TL将行数据与DOCX模板合并。
        - 创建或附加内容到输出DOCX文件。
        - 从模板复制段落和表格到输出文档。

### 错误处理

该应用程序处理以下异常：

- `ParseException`：命令行参数无效时抛出。
- `IOException`：文件读写操作期间抛出。
- `RuntimeException`：在文档处理过程中发生任何意外错误时抛出。

在出现错误时，会在控制台打印相应的消息。

### 示例

给定一个包含以下内容的Excel文件`data.xlsx`：

| 姓名 | 年龄 | 城市   |
|------|-----|--------|
| John | 30  | 纽约   |
| Jane | 25  | 伦敦   |

以及一个包含`${姓名}`、`${年龄}`和`${城市}`占位符的DOCX模板`template.docx`，运行以下命令：

```sh
java -jar target/your-jar-file.jar -i data.xlsx -t template.docx -o output.docx
```

将生成一个填充了`data.xlsx`数据的`output.docx`文件。

### 结论

该应用程序自动化了从Excel文件读取数据并生成基于模板的DOCX文档的过程，非常适合用于生成报告、信件或任何需要基于模板插入数据的文档。

有关进一步的定制和增强，请参考Apache POI、Apache Commons CLI和POI-TL库的官方文档。

[English Version](#english-version)