# EncodingConversion

**Repository Path**: qiao-developer/encoding-conversion

## Basic Information

- **Project Name**: EncodingConversion
- **Description**: 一款编码转换工具，将多种文本文件批量转换为 UTF-8 编码，适用于整理跨平台工程、解决中文乱码等场景。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UTF-8 编码转换工具

本项目提供命令行与图形界面两种方式，将多种文本文件批量转换为 UTF-8 编码，适用于整理跨平台工程、解决中文乱码等场景。

## 功能特点
- 自动检测原始编码（基于 `charset-normalizer`），仅在需要时转换。
- 支持文件/目录递归处理、扩展名过滤、忽略隐藏项。
- 可选择 Dry-run 预览、生成 `.bak` 备份，降低误操作风险。
- 图形界面支持拖拽导入与多线程执行，实时输出日志。

## 环境准备
```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```

## 命令行用法
```powershell
# 先预览再决定是否实际写入
python convert_to_utf8.py <目标路径> --dry-run --backup -e .txt .py

# 确认后去掉 --dry-run 即会写回 UTF-8
python convert_to_utf8.py <目标路径> --backup -e .txt .py
```
常用参数：
- `root`：必填，目标文件或目录。
- `-e/--ext`：仅处理指定扩展名，留空为全部。
- `--include-hidden`：包含隐藏文件/目录。
- `--backup`：转换前生成 `.bak` 备份。
- `--dry-run`：只打印转换计划，不写入。

## 图形界面用法（已提供图形化界面工具dist/gui_convert_to_utf8.exe）
```powershell
python gui_convert_to_utf8.py
```
- “选择文件/文件夹”或直接拖拽添加多个目标。
- “扩展名过滤”输入如 `.py,.txt`，留空表示全部。
- 勾选“预览模式 (不写入)”相当于 Dry-run，取消勾选即可写入。
- 勾选“保留 .bak 备份”可在同目录保留原文件副本。

## 打包为可执行文件
确保已激活虚拟环境，并安装 PyInstaller：
```powershell
pip install pyinstaller
```

### 命令行版本
```powershell
pyinstaller --onefile convert_to_utf8.py
```
生成 `dist\convert_to_utf8.exe`，命令行参数与脚本一致。

### 图形界面版本
```powershell
pyinstaller --onefile --noconsole \
  --add-data ".venv/Lib/site-packages/tkinterdnd2/tkdnd;tkinterdnd2/tkdnd" \
  gui_convert_to_utf8.py
```
生成 `dist\gui_convert_to_utf8.exe`，双击即可启动图形界面。

> 如换用绝对路径，记得使用正斜杠 `/` 或双反斜杠 `\\` 避免转义错误。

## 注意事项
- 推荐先使用 Dry-run + 备份，确认日志后再执行写入。
- 若检测失败或遇到二进制文件，会记录 `[SKIP]` 并跳过。
- 首次运行 exe 可能被安全软件拦截，标记为信任即可。
- Python 3.13 开始移除 `tkinter.tix`，项目内已内置兼容代码，打包时需确保携带 `tkdnd` 文件夹（见上文 `--add-data`）。

## 目录结构
```
EncodingConversion/
├─ convert_to_utf8.py        # 命令行脚本（核心逻辑）
├─ gui_convert_to_utf8.py    # 图形界面入口
├─ requirements.txt          # 依赖清单
└─ dist/                     # 打包输出目录（执行 PyInstaller 后生成）
```

如需拓展功能（例如增加日志文件、处理更多编码策略或打包安装程序），欢迎进一步交流。