# ExcelToWord

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

## Basic Information

- **Project Name**: ExcelToWord
- **Description**: 本程序将Excel表格数据转换成Word表格，可用于将Excel管理的用例直接转化成Word版的用例表格。同时实现了用户自定义配置模板，是一款较为通用的Excel转Word的程序，也可用于其他类似场景。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2023-08-19
- **Last Updated**: 2025-02-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 一、用户手册

## 1、功能介绍

本工具旨在解决编写Word版用例比较繁琐的问题，使用该工具后可以轻松将Excel的用例转为Word用例。

同时，该工具设计趋向于更大的通用性。使用者可以自定义模板、替换的内容、位置等，在较大程度上可以实现不修改业务源代码的情况下自定义生成模板，按需转换成想要的word文档。

工具主要原理：
 1. 将（源文件）Excel表格的数据读入到程序中，形成一行行的数据（如：用例）信息。
 2. 根据该行Excel表格中定义的功能级别（如：一级功能、二级功能等），生成对应的标题级别。
 3. 然后再根据word版本的表格模板（如：用例表格模板），拼接到想要拼接的word文档中。
 4. 重复步骤2和3，直到所有数据行都生成、替换完。
 
 最后生成、拼接的内容格式大致如下：
```
一级功能（标题内容）
    |
    `————————二级功能（标题内容）
    |        表格（如：用例）
    |
    `————————二级功能（标题内容）
    |        表格（如：用例）
    |
    `————————二级功能（标题内容）
                  |
                  `————————三级功能（标题内容）
                  |         表格（如：用例）
                  |
                  `————————三级功能（标题内容）
                           表格（如：用例）
```

## 2、使用步骤

以下我们以默认的用例生成来讲解如何使用，使用时主要涉及到“测试用例.xlsx”、“用例表格模板.docx”、“输出模板.docx”三个文件，文件均需放在与“ExcelToWordUtils.py”源代码文件放在同一目录下。

程序就是将“测试用例.xlsx”里面的每行数据、“用例表格模板.docx”拼接至“输出模板.docx”文件中，最后生成“用例结果-xxx。xlsx”。

如下是文件与程序对应的配置关系图，可以帮助理解对应关系。

![对应关系图](http://114.132.74.164:8088/Files/Gitee/ExcelToWord-001.jpg)

具体使用步骤如下：
- 步骤一：填写“测试用例.xlsx”
    - 蓝框（功能级别）：
        - 功能级别分别为“一级功能”、“二级功能”、...、“八级功能”，其中默认对应的标题级别分别为2、3、...、9级标题。
        - 下图测试用例填写示例中，只到了三级功能，如果实际项目中功能级别到四、五级功能等，插入列并按要求命名成“四级功能”、“五级功能”等。
        - 功能级别的内容填写方面，需要进行合并；同时如果当前用例没有三级标题（如示例图的第一、二行），则填写“/”即可。
    - 红框（用例相关标题）：红框的标题，需要与“用例表格模板.docx”的“${xxx}”一一对应上，在内容填写上按自己需要填写即可。
    - 绿框（存在截图）：
        - 如果用例相关信息中存在截图时，如实际结果中需要加入截图，则需以“$图片名称加后缀名$”的格式为图片做占位标记。
        - 同时在源代码同一目录下的“Images”下存放对用的图片，如默认示例的“xxx-001.jpg”

![测试用例](http://114.132.74.164:8088/Files/Gitee/ExcelToWord-002.jpg)

- 步骤二：“用例表格模板.docx”示例，需要确保“${xxx}”与“测试用例.xlsx”的标题行对应上（默认的示例已对应上）。具体图示如下：

![用例表格模板](http://114.132.74.164:8088/Files/Gitee/ExcelToWord-003.jpg)

- 步骤三：填写完“测试用例.xlsx”文件后，并确保用例表格模板正确。即可执行程序“ExcelToWordUtils.py”的main方法。
- 步骤四：程序执行完成后，即会生成以“测试结果”为前缀的用例结果文件。

**注意：**
- **最后一级的功能不能合并，合并了生成会出现问题。**
- 如果是用打包后的exe程序来执行，需要在与exe程序同一目录下填充好“测试用例.xlsx”、“用例表格模板.docx”、“输出模板.docx”、“Images文件夹”，然后双击程序运行即可。
- 打包exe程序的方法，请参考“二、开发指引”的“3、打包指引”。

## 3、模板示例

该项目已准备两个已打包好的示例，分别在“示例/CNAS示例”、“示例/默认模板示例”路径下。这两个示例的文件中，只有“测试用例.xlsx”和“用例表格模板.docx”两个文件是根据特定表格设计的，不用修改源码等其他内容。

运行时推荐双击“【运行推荐】执行程序.bat”，此方式运行时如果程序报错的话，可以查看到错误日志。如果双击ExcelToWordUtils.exe运行方式，程序执行完后会直接自动关闭窗口，看不到执行结果。

# 二、开发指引

## 1、开发环境&版本

建议版本与下述保持一致，以避免出现不必要的错误：
- python版本：python-3.8.6-amd64
- 第三方依赖：
    - word文档读写：python-docx/0.8.11
    - excel读：xlrd/1.2.0
    - python-docx可能用到的依赖：lxml/4.8.0

## 2、整体代码逻辑介绍

注：为方便将程序打包成exe可执行文件，本项目将所有代码放置一个文件中。

本项目共设计三个类以及一个程序运行入口：
- Const类：该类主要用作全局配置。具体配置作用如下：
    - functionPointLevel配置：对应“测试用例.xlsx”的功能级别的标题。此处可修改，但需要与“测试用例.xlsx”的功能级别的标题对应上。
    - titleLevel配置：对应“测试用例.xlsx”的功能级别的标题等级。如“一级功能”对应的文档标题等级是“2级标题”，以此类推。
    - excelFileName配置：对应“测试用例.xlsx”文件名称。此处配置修改时，对应的原数据文件名称也要修改成一致。
    - sheetName配置：对应“测试用例.xlsx”文件中的sheet页名称。此处配置修改时，也需对应修改成一致。
    - wordTableTemplateFileName配置：与“用例表格模板.docx”表格模板对对应上。此处配置修改时，也需对应修改成一致。
    - exportTemplateFileName配置：与“输出模板.docx”对应上。此处配置修改时，也需对应修改成一致。
    - exportNamePrefix配置：输出结果文件的前缀名称。
    - imagesPath配置：如果数据源excel文件中有截图，则需将截图放在该文件夹下。此处配置修改时，“Images”文件夹名称也要对应修改成一致。
    - picWidth配置：如果数据源excel文件中有截图，此处修改控制图片宽度，以免图片太大而溢出。
- Transfer类：该类主要用于将Excel数据转换成Word，会生成文章结构及对应的用例表格。具体方面介绍如下：
    - doTransfer方法：遍历Excel数据行，按数据行信息，分别调用addTitle方法、addTable方法、replaceTableContent方法等，逐行生成标题、拼接表格、替换表格内容。
    - addTitle方法：在文档中添加一个文档标题。
    - addTable方法：从表格模板中复制一份到待输出的文档中。
    - replaceTableContent方法：替换表格的“${xxx}”内容。
    - addPicture方法：为段落、表格添加图片。
- ExcelHelper类：
    - read_by_list方法：读取用例表格，保存至list中，其中每个list的元素是list列表。
    - read_by_dict方法：读取用例表格，保存到list中，其中每个list的元素为dict字典。
- main程序入口，执行流程大致如下：
    - 步骤一：读取Excel表格数据、Excel表格的表头
    - 步骤二：读取待拼接的输出模板文档
    - 步骤三：读取表格模板
    - 步骤四：执行转换操作
    - 步骤五：将转换结果输出

Const配置类与相关文件的对应关系图：

![对应关系图](http://114.132.74.164:8088/Files/Gitee/ExcelToWord-001.jpg)

## 3、打包指引

如果需要将该程序打包成exe程序。则需安装“pyinstaller”打包工具。

PyInstaller可以将Python代码和依赖项打包成一个独立的可执行文件，无需安装Python解释器或其他依赖项。

以下是在PyCharm中使用PyInstaller打包Python项目成exe文件的一般步骤：

1. 在PyCharm中打开你的Python项目。

2. 确保你已经安装了PyInstaller。你可以通过在终端中运行以下命令来安装PyInstaller：

   ```
   pip install pyinstaller
   ```

3. 打开PyCharm的终端。在底部工具栏上，你可以找到终端按钮。

4. 在终端中，导航到你的项目目录。可以使用`cd`命令来切换目录。

5. 运行以下命令来使用PyInstaller打包你的项目：

   ```
   pyinstaller --onefile ExcelToWordUtils.py
   ```

   这个命令将在项目目录中创建一个`dist`文件夹，并在其中生成可执行的exe文件。

6. 打包完成后，你可以在`dist`文件夹中找到生成的exe文件。这个exe文件可以在没有Python解释器的环境中运行。

请注意，PyInstaller会将你的Python代码和依赖项打包成一个独立的exe文件，但在某些情况下可能会遇到一些问题。例如，如果你的项目依赖于一些动态加载的资源文件或第三方库，可能需要进行额外的配置。你可以查阅PyInstaller的文档以获取更多详细信息和解决方案。

另外，打包成exe文件可能会因操作系统的不同而有所差异。如果你希望在不同的操作系统上打包exe文件，可以考虑使用PyInstaller的`--platform`选项来指定目标平台。例如，如果你希望在Windows上打包exe文件，可以使用以下命令：

```
pyinstaller --onefile --platform=win32 ExcelToWordUtils.py
```

这将生成一个适用于Windows平台的exe文件。

## 4、待完善内容

目前为初始版本，实现了基本功能，未对配置、内容等填写进行填写错误提示、检查等。同时，在自定义模板内容时，容易出错。

# 常见问题

## 1、表格模板单元格样式问题

表格模板的单元格需保持“正文”的样式，有些表格的单元格可能是“列表”等样式，这样在生成时，可能会影响到标题序号的自动生成。

## 2、生成后标题无自动序号

本程序的默认示例中的“输出模板.docx”的标题样式，已经是预设好了样式，程序生成标题时就会自动生成序号。

如果你自定义的输出模板没有给标题预设样式，需要先给输出模板的标题预设自动标题的样式。