# excel-import-tool

**Repository Path**: loveliulm_admin/excel-import-tool

## Basic Information

- **Project Name**: excel-import-tool
- **Description**: excel字段转换工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel数据导入工具 - 使用说明书

## 一、工具概述

### 1.1 功能简介
本工具用于将客户提供的Excel数据按列名匹配导入到指定的模板文件中。通过自动识别字段名并建立映射关系，实现数据的快速迁移和格式转换。

### 1.2 核心特点
- **智能化匹配**：自动按字段名进行列匹配，无需手动指定列对应关系
- **灵活配置**：支持自定义模板页签、字段行号、数据起始行号
- **可视化预览**：导入前可预览字段匹配结果，确保数据准确性
- **进度显示**：实时显示导入进度，让用户了解操作状态

### 1.3 适用场景
- 客户提供的Excel数据需要按照固定模板格式整理
- 批量数据录入到标准化模板
- 数据迁移和格式转换

---

## 二、系统要求

### 2.1 运行环境
- 操作系统：Windows 7/8/10/11
- Python版本：3.6及以上
- 依赖库：openpyxl

### 2.2 安装依赖
```bash
pip install openpyxl
```

---

## 三、使用方法

### 3.1 启动工具
在命令行中运行：
```bash
python excel_import_tool.py
```

### 3.2 界面说明

工具界面包含以下输入项：

| 输入项 | 说明 | 默认值 |
| :--- | :--- | :--- |
| **源文件路径** | 客户提供的Excel文件路径 | 无（需选择） |
| **模板文件路径** | 目标模板Excel文件路径 | 你的模板路径 |
| **目标页签名** | 模板中要导入数据的页签名称 | 需要转换的页签 |
| **模板字段行** | 模板中字段名所在的行号（从1开始） | 6 |
| **起始行** | 从第几行开始覆盖填写数据 | 9 |

### 3.3 操作步骤

#### 步骤1：选择源文件
1. 点击「源文件路径」右侧的「浏览」按钮
2. 在弹出的文件选择对话框中，选择客户提供的Excel文件（.xlsx格式）

#### 步骤2：确认模板文件路径
- 系统默认模板路径为 `你的模板路径`
- 如需修改，点击「浏览」按钮选择其他模板文件

#### 步骤3：配置导入参数
- **目标页签名**：输入模板中要导入数据的页签名称
- **模板字段行**：输入模板中字段名所在的行号
- **起始行**：输入从第几行开始覆盖填写数据

#### 步骤4：预览匹配结果（推荐）
1. 点击「预览匹配」按钮
2. 查看列名匹配情况，确认所有需要的字段都已成功匹配
3. 如果有未匹配的字段，检查字段名是否一致或调整配置

#### 步骤5：执行数据导入
1. 确认配置正确后，点击「开始导入」按钮
2. 等待进度条完成
3. 导入成功后会显示导入行数、匹配列数和保存路径

---

## 四、数据格式要求

### 4.1 源文件格式要求
- 文件格式：.xlsx
- 第一行必须为字段名（表头）
- 数据从第二行开始

### 4.2 模板文件格式要求
- 文件格式：.xlsx
- 指定的「目标页签」必须存在
- 指定的「模板字段行」包含字段名
- 数据将从「起始行」开始覆盖填写

### 4.3 字段匹配规则
- 字段名匹配时会自动去除首尾空格
- 字段名区分大小写（例如："姓名" 和 "姓名 " 视为相同，但 "Name" 和 "name" 视为不同）
- 只有在模板和源文件中都存在的字段才会进行数据导入

---

## 五、业务场景示例

### 场景：仓库档案数据导入

假设您收到客户提供的Excel文件，包含仓库信息，需要导入到公司标准模板中：

**客户源文件结构**（第1行为表头）：
| 仓库编码 | 仓库名称 | 所在城市 | 负责人 |
| :--- | :--- | :--- | :--- |
| WH001 | 北京仓库 | 北京 | 张三 |
| WH002 | 上海仓库 | 上海 | 李四 |

**模板文件结构**（第6行为表头）：
| 仓库编号 | 仓库名称 | 所属城市 | 联系人 | 备注 |
| :--- | :--- | :--- | :--- | :--- |
| （空） | （空） | （空） | （空） | （空） |

**配置参数**：
- 源文件路径：选择客户Excel文件
- 模板文件路径：选择目标文件路径
- 目标页签名：目标文件页签名
- 模板字段行：目标匹配字段所在行
- 起始行：目标覆盖起始行

**匹配结果**：
eg:
- ✓ 仓库编号 → 仓库编码
- ✓ 仓库名称 → 仓库名称
- ✓ 所属城市 → 所在城市
- ✗ 联系人 → 未匹配（源文件无此字段，名称不对应）
- ✗ 备注 → 未匹配（源文件无此字段）

**导入后效果**：模板第X行开始填充数据

---

## 六、注意事项

### 6.1 数据安全
- 工具会直接覆盖模板文件，请确保模板文件有备份
- 建议在导入前先复制模板文件作为备份

### 6.2 常见问题

**Q1：导入失败，提示"模板中不存在名为XX的页签"**
- 检查模板文件中是否存在指定的页签
- 确认页签名称输入正确（注意空格和大小写）

**Q2：预览时显示多个字段未匹配**
- 检查源文件和模板的字段名是否完全一致
- 注意字段名是否包含不可见字符（如空格、换行符）
- 可以手动修改字段名使其一致

**Q3：导入后部分数据为空**
- 检查源文件对应单元格是否有数据
- 确认字段匹配是否正确

**Q4：工具无法启动**
- 确认已安装Python环境
- 运行 `pip install openpyxl` 安装依赖库

### 6.3 技术支持
如遇到问题或需要定制功能，请联系技术支持。

---

## 七、版本记录

| 版本 | 日期 | 更新内容 |
| :--- | :--- | :--- |
| v1.0 | 2026-05-08 | 初始版本，支持基本导入功能 |

---

*文档版本：v1.0*  
*创建日期：2026年5月8日