# utools-excle-data-clean

**Repository Path**: fancy171101034/utools-excle-data-clean

## Basic Information

- **Project Name**: utools-excle-data-clean
- **Description**: utools的一个插件，完成Excel的数据清洗
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel 数据清洗

一款运行在 uTools 中的本地 Excel/CSV 数据整理工具。它可以从多个文件、多个 Sheet 和多张数据表中选择字段，统一字段名称、格式化数据并合并导出。

所有数据都在本机处理，不会上传到网络。

## 主要功能

- 支持 `.xlsx`、`.xls`、`.xlsm` 和 `.csv` 文件，一次最多添加 50 个文件。
- 支持点击选择文件或将文件直接拖入窗口。
- 自动遍历工作簿中的全部 Sheet，并识别一个 Sheet 内的多张数据表。
- 支持按文件、Sheet、数据表选择需要参与清洗的数据范围。
- 支持搜索、全选、清空和调整输出字段顺序。
- 支持修改输出字段名称，将不同原始字段合并为同一个输出字段。
- 支持日期、日期时间、布尔值和值映射格式化。
- 支持预览前 10 行结果并导出新的 Excel 文件。

## 使用方法

### 1. 上传文件

点击“选择文件”，或者将 Excel/CSV 文件拖入上传区域。文件解析成功后，可以查看每个文件包含的 Sheet 和数据表数量。

### 2. 圈选数据

选择需要参与合并的数据表和字段。字段既可以用树形方式查看，也可以切换为卡片方式查看。

取消选择某张表后，该表的数据不会进入预览和导出结果。

### 3. 设置字段

在“格式化”步骤中，可以拖动左侧字段调整输出顺序，并为每个字段设置：

- 输出字段名
- 日期或日期时间格式
- 布尔值显示文字
- 原值到新值的映射

无法识别或未匹配的值会保留原值。

### 4. 预览并导出

确认合并后的行数、输出字段数和预览数据，然后点击“导出清洗结果”。生成的 `.xlsx` 文件会保存到系统下载目录，并在文件管理器中定位。

## 同名字段合并规则

多个原始字段设置为同一个“输出字段名”时，最终只生成一个输出字段。

例如，将以下字段的输出字段名都设置为“名称”：

- 项目名称
- 建设单位及项目名称
- 建设单位

程序会按下面的规则处理每张表：

1. 只从当前表实际存在的字段中取值；不存在的字段直接忽略。
2. 如果当前表只有一个候选字段，则使用该字段。
3. 如果当前表同时存在多个候选字段，则使用字段排序最靠前的一个。
4. 字段顺序以“格式化”页面左侧列表的顺序为准，可以通过拖动调整优先级。
5. 所选字段的格式化规则会在合并前应用到对应值。

## 数据表识别规则

- 优先把包含“序号”“编号”或“序列号”的行识别为表头末行。
- 如果没有上述字段，则使用首个包含足够有效单元格的行作为候选表头。
- 表头上方连续的有效分组行会作为多级表头处理。
- 重复的子字段会附带父级表头，以避免原始字段重名。
- 表头前仅包含一个有效内容的行会作为表名。
- 空白行会被跳过，不会因为数据区中的空行直接拆分数据表。

自动识别结果可能受到源文件排版方式影响，导出前请在“数据圈选”页面确认识别范围。

## 本地开发

需要 Node.js 18 或更高版本、npm 和 uTools 开发者工具。

安装依赖并启动 Vite：

```bash
npm install
npm run dev
```

开发服务默认运行在 `http://localhost:5173`。`public/plugin.json` 已配置开发入口，可在 uTools 开发者工具中载入项目根目录进行调试。

生产构建：

```bash
npm run build
```

构建产物位于 `dist/`。

## 验证脚本

验证同名输出字段的合并和排序优先规则：

```bash
npm run verify:merge
```

使用样例工作簿验证数据表和多层表头识别：

```bash
npm run verify:sample
```

`verify:sample` 需要仓库中存在 `doc/数据表.xlsx`；没有该样例文件时，此命令会提示文件不存在。

## 技术栈

- Vue 3
- Element Plus
- Vite
- SheetJS（xlsx）
- uTools API