tools/dexcel/README.md

# dexcel - Excel 读写工具 📊

一个简单易用的命令行 Excel 处理工具，支持查询、统计、插入、更新、删除和样式设置操作。

**当前版本**: v0.4.0

## ✨ 功能特性

### 核心操作
- 🔍 **query**: 灵活查询 Excel 数据，支持行范围选择
- 📊 **count**: 快速统计行数，适合脚本使用
- ➕ **insert**: 插入新行，支持指定位置或追加到末尾
- ✏️ **update**: 更新现有数据，支持部分列更新
- ❌ **delete**: 删除行，支持灵活的起始位置和数量控制
- 🎨 **style**: 设置样式（行高、列宽、自动换行）

### 通用特性
- 📑 **多 Sheet 支持**: 所有操作都支持 `--sheet` 参数指定工作表
- 🔢 **负数索引**: 支持负数行号（-1 表示最后一行）
- ⚠️ **安全确认**: delete 操作默认需要用户确认，可用 `-y` 跳过
- 💾 **样式保留**: 使用 umya-spreadsheet 库，完整保留 Excel 样式
- 📤 **表格输出**: query 以美观的表格格式显示数据
- 📅 **日期智能**: 自动识别和格式化日期时间单元格
- 🧹 **备份清理**: 操作成功后自动删除 .bak 备份文件
- ↩️ **换行支持**: 智能处理各种换行符格式，自动开启换行并调整行高

## 📦 安装

### 从源码编译

```bash
cd dexcel
cargo build --release
```

编译后的可执行文件位于 `target/release/dexcel.exe` (Windows)

### 全局安装

```bash
cargo install --path . --force
```

安装后可直接使用 `dexcel` 命令。

## 🚀 使用方法

**基本格式：**
```bash
dexcel <文件路径> <操作> [参数]
```

**注意：文件路径是第一个位置参数，不需要 `--file` 标志！**

### 1. 查询数据 (query)

```bash
# 查看整个文件（默认显示最后20行）
dexcel data.xlsx query

# 查看前5行
dexcel data.xlsx query 5

# 查看最后3行
dexcel data.xlsx query -3

# 查看最后一行
dexcel data.xlsx query --last

# 从第10行开始查看
dexcel data.xlsx query --start 10

# 指定 Sheet 名称
dexcel data.xlsx query --sheet "Sales"
```

#### query 参数说明
- `[COUNT]`: 获取行数（正数从前，负数从后），默认0显示最后20行
- `--start <START>`: 开始行号（支持负数）
- `--last`: 获取最后一行
- `--sheet <SHEET>`: Sheet 名称（可选，默认第一个 Sheet）

### 2. 统计行数 (count)

```bash
# 统计总行数
dexcel data.xlsx count

# 统计指定 Sheet 的行数
dexcel data.xlsx count --sheet "Sales"
```

#### count 参数说明
- `--sheet <SHEET>`: Sheet 名称（可选，默认第一个 Sheet）

**输出**: 只输出一个数字，表示总行数，适合脚本中使用。

### 3. 创建新文件 (new)

```bash
# 创建新的 Excel 文件
dexcel new mydata.xlsx

# 指定 Sheet 名称
dexcel new mydata.xlsx --sheet "数据表"
```

#### new 参数说明
- `<NAME>`: 文件名（必填）**必需**
- `--sheet <SHEET>`: Sheet 名称（可选，默认为 Sheet1）

**注意**：如果文件已存在，会报错提示。

### 3. 插入数据 (insert)

```bash
# 追加数据到末尾（文件必须已存在）
dexcel data.xlsx insert "张三|18|北京"

# 在指定位置插入（第2行）
dexcel data.xlsx insert "李四|20|上海" --row 2

# 使用不同分隔符
dexcel data.xlsx insert "王五,25,广州" --split ","

# 指定 Sheet
dexcel data.xlsx insert "数据" --sheet "Sheet2"
```

#### insert 参数说明
- `<VALUE>`: 要插入的值（用 split 分隔列）**必需**
- `--row <ROW>`: 插入位置（不指定则追加到末尾）
- `--sheet <SHEET>`: Sheet 名称（可选）
- `--split <SPLIT>`: 分隔符（默认 |）

**注意**：insert 命令要求文件必须已存在，如果文件不存在会报错。

**换行符支持**：
```bash
# 使用字面量 \n（单引号）
dexcel data.xlsx insert '第一行\n第二行\n第三行|其他列'

# 使用 PowerShell 转义（双引号 + `r`n）
dexcel data.xlsx insert "Line1`r`nLine2,Col2" --split ","

# 自动开启换行并调整行高
# 无需手动设置，程序会自动检测换行符并调整
```

### 4. 更新数据 (update)

```bash
# 更新整行（从第1列开始）
dexcel data.xlsx update "赵六|22|深圳" --row 2

# 更新部分列（从第2列开始）
dexcel data.xlsx update "新年龄" --row 5 --cell 2

# 更新多列（从第3列开始）
dexcel data.xlsx update "新城市|新备注" --row 4 --cell 3

# 指定 Sheet
dexcel data.xlsx update "新值" --row 1 --sheet "Sheet2"
```

#### update 参数说明
- `<VALUE>`: 要更新的值（用 split 分隔列）**必需**
- `--row <ROW>`: 行号（必需，支持负数）
- `--cell <CELL>`: 起始列号（从1开始，默认1）
- `--sheet <SHEET>`: Sheet 名称（可选）
- `--split <SPLIT>`: 分隔符（默认 |）

**换行符支持**：
```bash
# 更新单元格为多行文本
dexcel data.xlsx update '新内容\n带换行' --row 5

# 自动开启换行并调整行高
dexcel data.xlsx update "Line1`nLine2" --row 3 --split ","
```

### 5. 删除数据 (delete)

```bash
# 删除第5行（需要确认）
dexcel data.xlsx delete 5

# 从第3行开始删除5行（跳过确认）
dexcel data.xlsx delete 3 --count 5 -y

# 删除最后一行
dexcel data.xlsx delete -1 -y

# 删除最后3行
dexcel data.xlsx delete -3 --count 3 -y

# 指定 Sheet
dexcel data.xlsx delete 1 --sheet "Sheet2"
```

#### delete 参数说明
- `<START>`: 起始行号（必需，支持负数）
  - 正数：从前往后数（如 `5` 表示第5行）
  - 负数：从后往前数（如 `-1` 表示最后一行）
- `--count <COUNT>`: 删除的行数（默认1）
- `-y, --yes`: 跳过确认
- `--sheet <SHEET>`: Sheet 名称（可选）

**使用示例**:
- `dexcel file.xlsx delete 5` - 删除第5行(需确认)
- `dexcel file.xlsx delete 5 --count 3 -y` - 从第5行开始删除3行(跳过确认)
- `dexcel file.xlsx delete -1 --count 2 -y` - 删除最后2行

**注意**: delete 操作默认需要用户确认（输入 y 继续），可使用 `-y` 跳过确认。

### 6. 设置样式 (style)

```bash
# 设置第1行的行高
dexcel data.xlsx style --rows 1 --row-height 30

# 设置A列的列宽
dexcel data.xlsx style --cols 1 --col-width 20

# 设置自动换行
dexcel data.xlsx style --rows 1 --cols 1 --wrap-text

# 组合设置
dexcel data.xlsx style --rows 1 2 3 --cols 1 2 --row-height 25 --col-width 15 --wrap-text

# 指定 Sheet
dexcel data.xlsx style --rows 1 --row-height 20 --sheet "Sheet2"
```

#### style 参数说明
- `--rows <ROWS>`: 行号列表（支持负数，不指定则应用到所有行）
- `--cols <COLS>`: 列号列表（不指定则应用到所有列）
- `--row-height <ROW_HEIGHT>`: 行高（像素）
- `--col-width <COL_WIDTH>`: 列宽（字符数）
- `--wrap-text`: 启用自动换行
- `--sheet <SHEET>`: Sheet 名称（可选）

## 💡 使用示例

### 示例 1: 创建学生信息表

```bash
# 创建表头
dexcel students.xlsx insert "姓名|年龄|班级"

# 添加学生数据
dexcel students.xlsx insert "张三|18|一班"
dexcel students.xlsx insert "李四|19|二班"
dexcel students.xlsx insert "王五|20|三班"

# 查看所有数据
dexcel students.xlsx query

# 统计总行数
dexcel students.xlsx count
```

### 示例 2: 数据查询和分析

```bash
# 查看前5行
dexcel data.xlsx query 5

# 查看最后10行
dexcel data.xlsx query -10

# 从第50行开始查看
dexcel data.xlsx query --start 50

# 导出到文件
dexcel data.xlsx query > output.txt

# 使用逗号分隔
dexcel data.xlsx query --split ","
```

### 示例 3: 数据更新

```bash
# 更新第2行的所有数据
dexcel data.xlsx update "新姓名|新年龄|新城市" --row 2

# 只更新第2行的第2列
dexcel data.xlsx update "新年龄" --row 2 --cell 2

# 批量更新（脚本）
for i in 2 3 4 5; do
    dexcel data.xlsx update "已审核" --row $i --cell 4
done
```

### 示例 4: 数据清理

```bash
# 删除第5行
dexcel data.xlsx delete 5 -y

# 从第10行开始删除5行
dexcel data.xlsx delete 10 --count 5 -y

# 删除最后3行
dexcel data.xlsx delete -3 --count 3 -y
```

### 示例 5: 多 Sheet 操作

```bash
# 在不同 Sheet 中操作
dexcel data.xlsx insert "数据1" --sheet "Sheet1"
dexcel data.xlsx insert "数据2" --sheet "Sheet2"

# 查询指定 Sheet
dexcel data.xlsx query --sheet "Sales"

# 统计指定 Sheet 的行数
dexcel data.xlsx count --sheet "Sales"
```

### 示例 6: 设置样式

```bash
# 设置第1行的行高为30像素
dexcel data.xlsx style --rows 1 --row-height 30

# 设置A列的列宽为20字符
dexcel data.xlsx style --cols 1 --col-width 20

# 设置自动换行
dexcel data.xlsx style --rows 1 --cols 1 --wrap-text

# 组合设置：多行多列，设置行高、列宽和自动换行
dexcel data.xlsx style --rows 1 2 3 --cols 1 2 --row-height 25 --col-width 15 --wrap-text

# 指定 Sheet
dexcel data.xlsx style --rows 1 --row-height 20 --sheet "Sheet2"
```

### 示例 7: 处理多行文本

```bash
# 插入带换行的内容（单引号中使用 \n）
dexcel data.xlsx insert '地址：北京市\n朝阳区\n建国路100号|备注'

# 使用 PowerShell 转义符（双引号中使用 `r`n）
dexcel data.xlsx insert "Line1`r`nLine2`r`nLine3,Col2" --split ","

# 更新为多行文本
dexcel data.xlsx update '说明：第一项\n说明：第二项' --row 2

# 程序会自动：
# 1. 识别并转换所有换行格式（\r\n, \n, `r`n）
# 2. 开启单元格的自动换行功能
# 3. 根据行数自动调整行高（每行约15磅）
```

## 📊 输出格式

### query 输出（表格格式）
```
┌──────┬──────┬──────┐
│ 姓名 │ 年龄 │ 城市 │
├──────┼──────┼──────┤
│ 张三 │ 25   │ 北京 │
├──────┼──────┼──────┤
│ 李四 │ 30   │ 上海 │
└──────┴──────┴──────┘

共输出 2 行数据，3 列
```

**特点**:
- ✅ 使用美观的表格格式（基于 tabled 库）
- ✅ 自动对齐列宽
- ✅ 清晰的分隔线和边框
- ✅ 显示行数和列数统计
- ✅ 易于阅读和查看

### count 输出
```
100
```

**特点**:
- 只输出一个数字
- 适合脚本中使用
- 可与其他命令组合

### 操作反馈

**insert 成功**:
```
✓ 操作成功：已创建新文件并插入一行数据
  文件: data.xlsx, Sheet: Sheet1
```

**update 成功**:
```
✓ 操作成功：已更新第 5 行，从第 1 列开始
  文件: data.xlsx, Sheet: Sheet1
```

**delete 成功**:
```
✓ 已删除第 5 至 7 行（共 3 行）
```

## ⚙️ 技术细节

### 依赖库

- **umya-spreadsheet**: Excel 读写库，完整保留样式，支持 .xlsx 格式
- **clap**: 命令行参数解析库
- **tabled**: 表格格式化输出库
- **chrono**: 日期时间处理库
- **thiserror**: 错误处理库

### 工作原理

#### 工作流程
1. 打开 Excel 文件（使用 umya-spreadsheet）
2. 选择指定的 Sheet（默认第一个）
3. 执行相应操作（查询/插入/更新/删除/样式设置）
4. 保存文件（保留原有样式）

### 数据类型支持

**读取时支持:**
- 字符串 (String)
- 整数 (Int)
- 浮点数 (Float)
- 布尔值 (Bool)
- 日期时间 (DateTime) - 自动识别并格式化
  - `2024-01-15` → 显示为 `2024-01-15`
  - `2024-12-25 14:30:00` → 显示为 `2024-12-25 14:30:00`
  - `14:30:00` → 显示为 `14:30:00`
- 空值 (Empty)
- 错误值 (Error)

**写入时:**
- 所有数据都作为字符串写入
- 日期时间自动识别并转换为 Excel 序列号
- 样式完全保留
- **换行符智能处理**：
  - 真正的 `\r\n` (ASCII 13+10) → 转换为 `\n`
  - 字面量 `\r\n` (4个字符) → 转换为 `\n`
  - 字面量 `\n` (2个字符) → 转换为 `\n`
  - 自动开启单元格自动换行
  - 自动调整行高（每行约15磅）

## ⚠️ 注意事项

1. **索引从 1 开始**: 行和列的索引都是从 1 开始，不是 0
2. **负数索引**: `-1` = 最后一行/列，`-2` = 倒数第二
3. **文件必须存在**: insert/update/delete 操作要求文件必须已存在
4. **分隔符默认**: 默认使用 `|` 分隔列
5. **文件格式**: 仅支持 `.xlsx`，不支持 `.xls`
6. **删除需确认**: delete 操作默认需要用户确认，可用 `-y` 跳过
7. **日期自动识别**: 自动识别并格式化日期单元格 (如 `2024-01-15`, `2024-12-25 14:30:00`)
8. **样式保留**: 使用 umya-spreadsheet 库，完整保留 Excel 样式
9. **备份清理**: 操作成功后自动删除 .bak 备份文件
10. **不可撤销**: delete 操作不可撤销，请谨慎操作！
11. **样式设置**: style 命令可设置行高、列宽、自动换行等样式
12. **换行处理**: insert/update 自动处理换行符，开启自动换行并调整行高

### 限制

**读取限制:**
- 公式: 不计算公式，只读取原始值
- 图表: 不支持读取图表
- 宏: 不支持 VBA 宏
- 大文件: > 10MB 的文件可能较慢

**写入限制:**
- 无公式: 不能写入公式
- update 会覆盖目标单元格的原有内容
- insert 会将原有数据下移

**优势:**
- ✅ 完整保留 Excel 样式（颜色、字体、边框等）
- ✅ 支持行高、列宽、自动换行等样式设置
- ✅ 插入/删除时自动调整样式

## 🔧 常见问题

### Q1: 如何查看文件有多少行？

```bash
dexcel data.xlsx count
```

### Q2: 如何追加多行数据？

多次调用 insert 命令：
```bash
dexcel data.xlsx insert "数据1|数据2"
dexcel data.xlsx insert "数据3|数据4"
```

### Q3: 负数参数怎么用？

```bash
dexcel data.xlsx query -5      # 最后5行
dexcel data.xlsx delete -1 -y  # 删除最后一行
```

### Q4: 如何处理中文内容？

直接传入，完全支持 UTF-8：
```bash
dexcel data.xlsx insert "张三|18|北京"
```

### Q5: 如何在脚本中使用 count？

```bash
# 获取行数并存储到变量
$lines = dexcel data.xlsx count

# 条件判断
if ((dexcel data.xlsx count) -gt 100) {
    Write-Host "文件超过100行"
}
```

### Q6: 删除操作能撤销吗？

不能撤销，请谨慎操作！建议先备份文件。

### Q7: 如何跳过删除确认？

使用 `-y` 或 `--yes` 参数：
```bash
dexcel data.xlsx delete 5 --count 3 -y
```

### Q8: 如何处理多行文本？

**方法 1: 使用单引号 + 字面量 \n**
```bash
dexcel data.xlsx insert '第一行\n第二行\n第三行'
```

**方法 2: 使用 PowerShell 双引号 + `` `r`n ``**
```powershell
dexcel data.xlsx insert "Line1`r`nLine2`r`nLine3"
```

**方法 3: 使用 Bash/Shell**
```bash
dexcel data.xlsx insert $'Line1\nLine2\nLine3'
```

程序会自动：
- ✅ 识别并转换所有换行格式
- ✅ 开启单元格自动换行
- ✅ 根据行数自动调整行高（每行约15磅）
- ✅ 保留原有样式不变

### Q9: 行高会自动调整吗？

是的！当检测到单元格包含换行符时，程序会：
1. 计算行数（换行符数量 + 1）
2. 估算所需行高（每行约15磅）
3. 只在当前行高小于估算值时才调整
4. 不会覆盖用户手动设置的行高

如果需要精确控制行高，可以使用 style 命令：
```bash
dexcel data.xlsx style --rows 5 --row-height 50
```

## 🎯 应用场景

### 1. 数据预览
快速查看大型 Excel 文件的部分内容：
```bash
dexcel large-file.xlsx query 5
```

### 2. 数据提取
提取特定数据并导出：
```bash
dexcel data.xlsx query -10 > last-rows.txt
```

### 3. 报告生成
创建报告模板：
```bash
dexcel report.xlsx insert "月度报告||||"
dexcel report.xlsx insert "日期|销售额|利润|备注"
```

### 4. 数据更新
批量更新某列数据：
```bash
dexcel data.xlsx update "新值" --row 5 --cell 2
dexcel data.xlsx update "新值" --row 6 --cell 2
```

### 5. 数据清理
删除错误数据：
```bash
# 删除第5行
dexcel data.xlsx delete 5 -y

# 从第10行开始删除5行
dexcel data.xlsx delete 10 --count 5 -y

# 删除最后3行
dexcel data.xlsx delete -3 --count 3 -y
```

### 6. 自动化脚本
PowerShell 批量导入：
```powershell
$students = @(
    @("张三", "18", "一班"),
    @("李四", "19", "二班")
)

foreach ($student in $students) {
    dexcel students.xlsx insert "$($student[0])|$($student[1])|$($student[2])"
}
```

## 📝 批处理脚本示例

### Windows 批量导入 (import.bat)

```batch
@echo off
echo 正在导入数据...

dexcel data.xlsx insert "ID|名称|数量"
dexcel data.xlsx insert "001|产品A|100"
dexcel data.xlsx insert "002|产品B|200"
dexcel data.xlsx insert "003|产品C|300"

echo 导入完成！
dexcel data.xlsx query
pause
```

### PowerShell 数据处理 (process.ps1)

```powershell
# 读取并处理数据
$output = dexcel data.xlsx query 100

# 过滤包含关键词的行
$filtered = $output | Select-String "关键词"

# 保存到文件
$filtered | Out-File -FilePath filtered.txt -Encoding UTF8

Write-Host "处理完成！" -ForegroundColor Green
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

可能的改进方向：
- 支持公式计算
- 支持更多数据类型
- 支持批量写入优化
- 支持复制 Sheet
- 添加数据验证功能
- 支持更多输出格式（CSV, JSON 等）
- 支持条件格式化

## 📄 许可证

本项目采用 MIT 许可证。

## 🙏 致谢

感谢以下开源项目：
- [umya-spreadsheet](https://github.com/nomiddlename/umya-spreadsheet) - 优秀的 Excel 读写库，完整保留样式
- [tabled](https://github.com/zhiburt/tabled) - 美观的表格格式化库
- [clap](https://github.com/clap-rs/clap) - 优秀的命令行参数解析库
- [chrono](https://github.com/chronotope/chrono) - 日期时间处理库
- [thiserror](https://github.com/dtolnay/thiserror) - 错误处理库

---

**Made with ❤️ using Rust**