# file2html-project

**Repository Path**: aylerh/file2html-project

## Basic Information

- **Project Name**: file2html-project
- **Description**: 主要功能：（1）高保真文件转html与html简易编辑（带格式刷）：最主要是docx2html，还有md/epub/txt等;（2）html在线编辑：可修改图片;（3）文件预览：不作为重点（因为是file-viewer自带了）（4）html2docx;(5)html2md;(6)html2epub;(7)html2txt;
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# File2HTML 文件高保真转换平台

File2HTML 是一个基于 Go (Gin) 后端实现的高保真文件转换与预览平台。用户可以通过统一且优雅的 Web 界面，一键将 Word (.docx), Markdown (.md), Epub 电子书以及数十种编程源码转换成高保真的 HTML 网页，同时支持将 HTML/ZIP 反向导出为 DOCX、Markdown (ZIP)、EPUB 电子书及 TXT 文本，并提供全功能的多文件批量双向转换能力。

## 性能
- html2docx预览较慢：因为涉及到转换，可能每页需要几十到几百毫秒；
- 下载快；

## 主要功能
- **正向转换与在线编辑（带格式刷）**：主打高保真 docx2html（精准还原缩进、字体、表格、列表排版），兼顾 md / epub / txt 及源码转网页；
- **全自动即选即转**：文件选择或拖拽后立即启动转换，自动就绪下载，无需手动点击转换按钮；
- **批量双向转换与智能打包**：
  - 支持多选文件与 ZIP 压缩包上传；
  - **多文件批量转 HTML**：批量将 DOCX / MD / EPUB / TXT / 源码转为带相对路径静态资源的高保真 HTML；
  - **HTML 批量转其他格式**：批量将 HTML / ZIP 反向导出为 DOCX / MD / EPUB / TXT；
  - **智能下载策略**：单文件转换按原格式直接输出，多文件自动合并为 ZIP 压缩包一键下载，配备实时百分比进度条与全屏模态框在线预览；
- **反向转换导出链条**：
  - `html2docx`: 将 HTML 或带图片相对链接的 ZIP 高保真转为 Word 文档（自研 OpenXML 生成引擎，支持 `border: none` 隐形表格、黑色细实线 `TableGrid`、百分比宽度与居中、页边距 9026 dxa 等比缩放防护、样式级联隔离防污染、软换行 `<br>` 段落拆分防字距拉伸）；
  - `html2md`: 将 HTML / ZIP 转为 Markdown 文档（含图片资源时自动导出包含 `images/` 的 ZIP 包）；
  - `html2epub`: 将 HTML / ZIP 编译构建并导出为标准的 EPUB 电子书 (.epub)；
  - `html2txt`: 将 HTML / ZIP 快速提取并导出纯文本 (.txt)；
- **文件直接预览**：支持多文本、源码及 DOCX 浏览器端极速原生预览。

## 主页样式
![1](./images/1.png)

### html转换与精简编辑-带格式刷
![2](./images/2.png)

### html在线编辑-带格式刷
支持：本地.html文件、图片.zip压缩包、或.docx/.md/.epub；
![3](./images/3.png)

### 批量转换
支持多文件/ZIP批量转HTML与HTML批量反向导出，单文件直接下载、多文件合并打包ZIP，上下通栏布局与实时进度反馈：


## 构建与运行

在本地运行以下命令，即可一键启动容器部署与调试：

```powershell
docker compose down; docker compose build; docker compose up -d
```

服务启动后，浏览器访问：`http://localhost:8566` 即可进行多文件上传转换与预览。

API Swagger 接口文档页地址：`http://localhost:8566/docs`。

## 解决痛点与使用技术

### 解决痛点
1. **完整双向反向导出**：不仅支持 Word/MD/EPUB 转 HTML，更自研支持将 HTML / ZIP 反向导出为 DOCX、MD (带图片 ZIP)、EPUB 及 TXT，提供全闭环文档处理流。
2. **多文件批量处理与智能打包**：解决了以往只能单文件转换的低效问题，支持多文档/ZIP 包批量上传，单文件按目标类型直接输出，多文件自动就地合并打包为 ZIP 供一键下载。
3. **全自动无缝交互体验**：上传即自动触发后台高保真转换，实时更新状态栏并展示下载链接，彻底解决多余按钮打断操作的问题。
4. **表格框线与排版级联隔离**：彻底修复了 CSS 样式继承导致的父级边框颜色（如 `#999`）污染内部表格、无边框表格（`border: none`）被强制画实线、以及 Word 中两端对齐（`both`）下软换行 `<br>` 导致字距异常拉伸的问题。
5. **高保真格式刷与排版一致性**：引入了全新“段落块级+行内字符”双重吸取的格式刷机制。能够跨目录节点提取排版属性（如字号大小、文字颜色、字体、对齐方式、缩进及 Flex 布局对齐等），并在目标段落上一键应用，解决了文档在线调整对不齐、大小不一的问题。
6. **轻量富图片编辑能力**：支持双击任意图片（`<img>`）唤起文件选择器，自动转化为 Base64 DataURL 进行实时无缝替换，并且支持选中图片按 `Backspace/Delete` 一键删除。编辑时带有悬停虚线（Dashed Hover）及手势暗示，兼顾高保真输出与流畅体验。
7. **零阻碍静默包更新**：将繁琐的手动下载、手动上传二次保存精简为一键“保存并更新包”机制。无阻碍保存并采用柔和变绿的状态栏通知提示，避免传统弹窗打断用户的创作流，后端自动重新 zipFolder 覆盖最新包以供下载。
8. **表格及目录键盘增强**：通过自定义按键拦截，修复了 `contenteditable` 容器内 table 单元格退格错乱与空格折叠问题，可自由敲击空格进行右端页码对齐。
9. **零服务端厚重依赖**：不依赖 LibreOffice Headless 或 Pandoc 等重量级软件，使用纯 Go 自研解析器与轻量编译器，构建极其迅速，内存开销极低。
10. **沙盒隔离与自动回收**：多用户上传预览采用隔离的 TaskID/BatchID 目录托管，并在后台开启定时垃圾回收器自动清理，保障磁盘空间不泄露。

### 使用技术
- **后端**：Go 1.24, Gin 框架, Swag API 自动构建, Goldmark 编译, Chroma v2 代码高亮, 自研 HTML2DOCX/MD/EPUB 转换引擎与 Batch 批次处理系统。
- **前端**：Vanilla HTML/CSS, 玻璃拟物态 UI, 双视区与上下通栏自适应布局, TreeWalker 高精细选区解析, Iframe 编辑沙盒技术。
- **架构**：Docker Multi-stage 极简分层构建（配合 Dockerfile.base 镜像级缓存构建优化）, Docker Compose 容器化部署。

## 致谢
- [goldmark](https://github.com/yuin/goldmark) - 标准的Go语言Markdown解析器
- [chroma](https://github.com/alecthomas/chroma) - 纯Go代码语法高亮渲染器
- [gin](https://github.com/gin-gonic/gin) - 高性能的轻量Go网关框架
- [file-viewer](https://github.com/flyfish-dev/file-viewer) - 优秀的多格式在线预览库