# read_write_excel

**Repository Path**: miaohf/read_write_excel

## Basic Information

- **Project Name**: read_write_excel
- **Description**: read_write_excel
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-08
- **Last Updated**: 2025-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 读取并新建 Excel 文档

本项目用于批量读取 `./docs/inputs` 下的所有 Excel 文件（支持 `.xlsx` 与 `.xls`），遍历每个文件的所有 Sheet，将首行识别为列头（header），其余行为数据（data），并在 `./docs/outputs` 中新建对应的 Excel 文档。输出文件命名为：`{original_filename}-{timestamp_date}.xlsx`（例如：`orders-20250101_101530.xlsx`）。

## 目录结构

- `docs/inputs/`: 放置待处理的源 Excel 文件
- `docs/outputs/`: 脚本输出的新 Excel 文件目录（脚本会自动创建）
- `scripts/process_excels.py`: 处理脚本
- `requirements.txt`: 依赖清单

## 功能说明

- 从 `./docs/inputs` 中读取所有 Excel 文档（可选递归扫描）
- 遍历每个文档的所有 Sheet：
  - 读取时将首行作为列头（header）
  - 其余行为数据（data）
  - **新增功能**：在每行末尾添加"在职状态"字段，默认值为"Y"
- 在 `./docs/outputs` 中创建新 Excel 文档，文件名格式：`{original_filename}-{YYYYMMDD_HHmmSS}.xlsx`
- 自动跳过临时/锁文件（如 `~$xxx.xlsx`）

## 环境要求

- Python 3.9+

## 安装步骤

1. 可选：创建并激活虚拟环境
2. 安装依赖
   ```bash
   pip install -r requirements.txt
   ```

## 使用方法

1. 将待处理的 Excel 文件放入 `./docs/inputs/`
2. 运行脚本：
   ```bash
   python scripts/process_excels.py
   ```
3. 可选参数：
   - 指定输入/输出目录：
     ```bash
     python scripts/process_excels.py --inputs /absolute/path/to/inputs --outputs /absolute/path/to/outputs
     ```
   - 递归扫描输入目录：
     ```bash
     python scripts/process_excels.py -r
     ```

## 输出规则

- 每个输入 Excel 会在 `./docs/outputs` 中生成一个新文件
- 新文件扩展名统一为 `.xlsx`
- 文件名：`{original_filename}-{YYYYMMDD_HHmmSS}.xlsx`
- 保留原有的 Sheet 名称与数据结构
- **数据增强**：每行末尾新增"在职状态"列，所有行的值设为"Y"

## 导出格式化规则

- 表头（第 1 行）：
  - 背景色：蓝色（`#4472C4`）
  - 字体：白色、加粗、Calibri、11pt
  - 对齐：水平居中、垂直居中
  - 边框：细线灰（四边）
- 数据区（第 2 行起）：
  - 字体：黑色、Calibri、11pt
  - 行样式：交替斑马纹（偶数行浅灰 `#F7F7F7`）
  - 边框：细线灰（四边）
- 冻结窗格：冻结首行（便于滚动查看）
- 列宽：按内容长度近似自适应，并留白（最大宽度 60）
- 行高：表头行适度加高（约 22）

## 代码实现逻辑（简述）

- 列举输入目录内的 Excel 文件（过滤 `~$` 前缀临时文件），可选递归
- 对于每个文件：
  - 获取其所有 Sheet 名称
  - 读取每个 Sheet：
    - 使用 `header=0` 将首行作为列头
    - 若空 Sheet 或异常，回退为 `header=None` 读取
    - 控制台打印该 Sheet 的列头，便于确认
  - **数据处理**：为每个 Sheet 添加"在职状态"列，所有数据行设为"Y"
  - 将各 Sheet 的数据写入新的 Excel（不写入行索引）
  - 使用 openpyxl 对每个 Sheet 应用样式（表头/数据样式、斑马纹、冻结首行、自适应列宽）
  - 输出文件名添加时间戳，避免覆盖

## 示例

- 输入：`docs/inputs/orders.xlsx`
- 输出：`docs/outputs/orders-20250101_101530.xlsx`
- **数据变化示例**：
  - 原数据：`姓名 | 年龄 | 部门`
  - 新数据：`姓名 | 年龄 | 部门 | 在职状态`

## 常见问题

- `.xls` 文件的读取需要 `xlrd`。本项目已在 `requirements.txt` 中包含 `xlrd`，用于读取 `.xls`。写出时统一使用 `openpyxl` 生成 `.xlsx`。
- 空 Sheet：会被创建为空 Sheet；若遇到列头解析异常，会回退为无表头模式读取。
- 多次运行：每次输出文件包含新的时间戳，不会覆盖之前结果。
- **新增字段**："在职状态"列会添加到所有 Sheet 的末尾，包括空 Sheet。

## 许可证

MIT