# file-converter

**Repository Path**: aigcJia/file-converter

## Basic Information

- **Project Name**: file-converter
- **Description**: 高端文件格式转换工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FormatFlow · 高端文件格式转换工具

本地离线运行的桌面文件转换应用，科技蓝高端设计，支持拖拽上传、格式选择、一键转换与下载，并具备 PDF 页码/目录、本地历史记录与快速打开文件夹等能力。

## 技术栈
- **前端**：原生 HTML + CSS + JavaScript（玻璃拟态 / 渐变科技风）
- **运行时**：Electron（窗口管理 + 本地文件系统 + 离线转换）
- **转换库**：
  - `marked` — Markdown → HTML
  - `mammoth` — DOCX → HTML
  - `html-docx-js` — HTML → DOCX
  - Electron `webContents.printToPDF` — HTML/MD/DOCX → PDF

## 支持的转换
| 输入 | 输出 |
|------|------|
| HTML | PDF ✅ |
| HTML | DOCX ✅ |
| Markdown | PDF ✅ |
| DOCX | PDF ✅ |

## 转换增强能力
- **PDF 页码**：输出为 PDF 时，页脚自动添加「第 X 页 / 共 Y 页」（基于 Electron `printToPDF` 的 `displayHeaderFooter`）。
- **PDF 目录（与页码对应）**：自动扫描文档 `h1–h3` 生成目录，为每个标题注入锚点 id，目录条目可点击跳转到对应章节；条目右侧显示按排版位置估算的页码，目录与正文页码一一对应。可在「PDF 选项」中分别开关「添加页码」「生成目录」。
- **本地历史记录**：所有转换结果通过 `localStorage` 持久化（源文件名、格式、输出、大小、时间，≤1.5MB 的结果同时保留二进制以便重新下载）。底部「转换历史」面板可重新下载或清空；超过配额的记录自动降级为仅元数据。
- **快速打开文件夹**：结果面板与历史记录在文件保存成功后提供「打开文件夹」按钮，调用 `shell.showItemInFolder` 直接定位到输出文件所在目录。

## 目录结构
```
file-converter/
├── main.js            # Electron 主进程 + 转换引擎 + IPC
├── preload.js         # 安全桥接（contextIsolation）
├── package.json       # 依赖与打包配置
├── src/
│   ├── index.html     # 界面结构
│   ├── styles.css     # 科技蓝主题样式
│   └── renderer.js    # 前端交互逻辑
└── scripts/
    ├── build.sh       # macOS 打包脚本
    └── build.ps1      # Windows 打包脚本
```

## 本地开发
```bash
npm install
npm start          # 启动桌面应用
```

## 打包为桌面 App
- **macOS**：`bash scripts/build.sh`  → 生成 `dist/FormatFlow-*.dmg` 与 `.zip`
- **Windows**：`powershell -ExecutionPolicy Bypass -File scripts/build.ps1` → 生成 `dist/FormatFlow Setup *.exe`（NSIS 安装包）

> 在 macOS 上交叉构建 Windows 包需安装 Wine；推荐在目标平台上直接运行对应脚本。
> 如需自定义图标，将 `icon.icns` / `icon.ico` 放入 `build/` 目录并在 `package.json` 的 `build.mac` / `build.win` 中指定 `icon`。

## 打包说明与注意事项
- **macOS**：`bash scripts/build.sh` 产出 `dist/FormatFlow-1.0.0-universal.dmg`（拖拽安装）与 `.zip`（便携版），universal 架构同时兼容 Intel 与 Apple Silicon。
  - 默认未签名（无 Developer ID），首次打开会触发 Gatekeeper 提示，右键「打开」即可运行；正式分发需配置证书并公证（`notarize`）。
- **Windows**：在 **Windows 机器**上运行 `scripts/build.ps1` 可直出标准 NSIS 安装包 `FormatFlow Setup *.exe`（无需 Wine）。
  - 在 macOS 上若想交叉编译出 `Setup.exe` 安装向导，需先装 Wine（`brew install --cask wine-stable`，须管理员权限）；缺少 Wine 时只能产出 **portable 版 `FormatFlow 1.0.0.exe`**（自解压、免安装直接运行，覆盖大多数使用场景）。
- 本机实测：已成功生成 universal `.dmg` 与 Windows x64 portable `.exe`。