# qt_file_io_demo —— Qt5 文件操作教学示例

一个 `QWidget` 布满按钮，分 5 个主题演示 Qt5 文件操作。每个按钮产生一个文件，落到
**可执行文件同目录的 `demo_output/`** 子目录下，界面顶部 `statusLabel` 始终显示绝对路径，
方便课堂逐个手动打开查看文件内容。

> 这是对仓库 `json_io`（控制台、仅内存序列化）的 GUI 补充：把 **QJson + 真实文件 I/O**
> 与其它文件操作主题一起，放进一个可点击演示的界面。

## 构建

仓库统一构建（走 `examples/CMakeLists.txt` 的 `add_teaching_example`）：

```bash
cmake -S . -B build -G Ninja -DBUILD_QT_PART=ON \
      -DCMAKE_PREFIX_PATH=$PWD/.qt514/5.14.2/gcc_64 -DCMAKE_BUILD_TYPE=Debug
cmake --build build --target qt_file_io_demo
tools/run_qt.sh qt_file_io_demo
```

单独打开（用本目录的独立 `CMakeLists.txt`）：

```bash
cmake -S . -B build -DCMAKE_PREFIX_PATH=<Qt5.14.2> -DCMAKE_CXX_COMPILER=<g++>
cmake --build build
```

离屏自动化验证（仿 p03 风格，200ms 自动退出、退出码 0）：

```bash
QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_file_io_demo
```

## 界面布局

```
┌─ statusLabel（显示绝对路径 + 每个演示的结果摘要）─────────────┐
├─ ① 基础文件操作  QFile 写/读/追加、QFileInfo、QDir            │
├─ ② 字符集编码    UTF-8 / Latin-1 / GBK / UTF-16LE / 乱码对比   │
├─ ③ 文本vs二进制  QTextStream / QDataStream / QIODevice::Text  │
├─ ④ 异常处理      Qt 返回值式 ｜ C++ try/catch（对照）          │
├─ ⑤ QJson 文件    写 / 读 / 改写                                │
├─ [在文件管理器中打开 demo_output]  [清空 demo_output]          │
└──────────────────────────────────────────────────────────────┘
```

## 各主题要点与产出文件

### ① 基础文件操作
| 按钮 | 产出文件 | 要点 |
|---|---|---|
| QFile 写文本 | `01_qfile_write.txt` | `QTextStream` 写；**坑点：Qt5 默认 codec 是系统区域编码（中文 Windows 常为 GBK），写中文必须显式 `setCodec("UTF-8")`** |
| QFile 读文本 | （读上一个） | 读端同样要 `setCodec("UTF-8")`，否则跨平台乱码 |
| 追加 vs 覆盖 | `01_append.txt` | `WriteOnly` 每次清空；`Append` 在末尾追加 |
| QFileInfo 信息 | `01_fileinfo.txt` | `exists / size / absoluteFilePath / absolutePath` |
| QDir 列目录 | — | `entryList(QDir::Files)` 列出 `demo_output` 内文件 |

### ② 字符集编码
| 按钮 | 产出文件 | 要点 |
|---|---|---|
| 写 UTF-8 | `02_utf8.txt` | `QString::toUtf8()`：中文每字 3 字节、ASCII 每字 1 字节 |
| 写 UTF-8 + BOM | `02_utf8_bom.txt` | 头部 `EF BB BF`（十六进制可见） |
| 写 Latin-1 | `02_latin1.txt` | `toLatin1()` 只能表 `U+0000~U+00FF`，中文超出变 `?` |
| 写 GBK | `02_gbk.txt` | `QTextCodec::codecForName("GBK")`；**未装 CJK codec 插件时返回 `nullptr`，界面列出当前可用编码并给出提示**。本仓库 MinGW Qt 未含 `plugins/codecs/`，故此按钮走降级提示（这本身就是教学点）；如需真正写 GBK，用 Qt Maintenance Tool 勾选安装 codecs 插件，或把 `plugins/codecs/` 拷到 Qt 的 plugins 目录 |
| 写 UTF-16LE | `02_utf16le.txt` | 手动写 `FF FE` BOM + 每字符固定 2 字节（低字节在前） |
| 乱码：错码读回 | （读 `02_utf8.txt`） | UTF-8 字节用 Latin-1 强解 → mojibake，说明「读写编码须一致」 |

> 用编辑器（VS Code / Notepad++）切换编码打开这些文件，可直观看到「同一段中文在不同编码下的字节差异」与乱码成因。

### ③ 文本方式 vs 二进制方式
| 按钮 | 产出文件 | 要点 |
|---|---|---|
| 文本写结构 | `03_struct_text.txt` | `QTextStream` 写 `name=张三 / age=20 / score=95.5`：可读但格式松散 |
| 二进制写结构 | `03_struct_bin.dat` | `QDataStream` 写 `qint32 + double + QString`：紧凑、带类型、可精确还原（程序内立即读回验证） |
| 对比大小 | — | `QFileInfo` 报告两文件字节数；用十六进制工具看 `.dat` 内部布局 |
| QIODevice::Text 换行 | `03_nl_text.txt` / `03_nl_bin.txt` | Windows 下 `Text` 标志把 `\n` 转 `\r\n`，不加则原样 `\n`；Linux 下两者相同 |

> `QDataStream` **务必 `setVersion(Qt_5_14)`**，否则 Qt 升级后二进制格式可能不兼容。

### ④ 异常与错误处理（两范式对照）
| 按钮 | 要点 |
|---|---|
| Qt: 打开不存在文件 | **Qt 范式**：`open()` 返回 `false` + `error()` / `errorString()`，不抛异常 |
| Qt: 只读模式写 | 只读 `QFile` 调 `write()` 返回 `-1` + `errorString()` |
| C++: ifstream 异常 | **C++ 范式**：`in.exceptions(failbit\|badbit)` 后打开失败抛 `std::ios_base::failure`，`try/catch` 捕获 |
| C++: throw + catch | 自定义异常 + `catch` 顺序（派生类在前、基类在后） |
| JSON: 损坏解析 | `04_broken.json`：`QJsonDocument::fromJson` 不抛异常，用 `QJsonParseError` 拿出错偏移与描述 |

> 核心对照：**Qt 几乎不用 C++ 异常**，错误经返回值/API 暴露；标准库流默认也不抛，需显式开启。
> 教学 LLVM 式「异常 vs 返回值」两种错误处理哲学的绝佳切入点。

### ⑤ QJson 文件读写
| 按钮 | 产出文件 | 要点 |
|---|---|---|
| 写 JSON 文件 | `05_student.json` | `QJsonObject` + `QJsonArray` → `QJsonDocument::toJson(Indented)` → 写文件 |
| 读 JSON 文件 | （读上一个） | `fromJson` → `object()` → 按键取值，`toArray()` 遍历数组 |
| 修改后回写 | （覆盖上一个） | 改 `score`、增 `grade`、删 `enrolled`，覆盖回写 |

## demo_output 在哪？

`QCoreApplication::applicationDirPath() + "/demo_output"` —— 即**可执行文件旁边**。
`tools/run_qt.sh` 运行时通常在 `build/` 下，所以路径形如 `build/qt_file_io_demo` 同级。
界面底部「在文件管理器中打开 demo_output」按钮可一键定位。

## 相关课程点

对应「C++ 方向 Day3」文件与数据格式章节；与 `json_io`（控制台 QJson 内存演示）、
`p03/ch11`（wiki 的 QFile/QTextStream/QDataStream）互为补充。