Skip to content

avenxyc/html_template_tool

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
html2docx
html2docx
 
 
template-editor
template-editor
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
template.html
template.html
 
 

Repository files navigation

HTML 模板工具集

一套完整的 HTML 模板工具链：可视化编辑 → 数据填充 → 导出 DOCX。

无需手写 HTML，通过可视化编辑器创建模板，配合 JSON 数据自动生成 Word 文档。

工具概览

工具 目录 功能 技术栈
📝 模板编辑器 template-editor/ 可视化编辑 HTML 表格模板 Electron + React + TipTap
🔄 模板引擎 + 转换器 html2docx/ 渲染模板并转换为 DOCX Python + Pandoc

快速开始

第一步：安装依赖

模板编辑器（需要 Node.js ≥ 18）

cd template-editor
npm install

HTML 转 DOCX 工具（需要 Python ≥ 3.8 + Pandoc）

# 安装 Pandoc（如果没有）
# Windows: winget install pandoc
# macOS:   brew install pandoc

cd html2docx
pip install -r requirements.txt

工作流时序图

sequenceDiagram
    autonumber

    actor 用户

    participant 编辑器 as 📝 模板编辑器
    participant 模板 as 📄 HTML 模板文件
    participant 数据 as 📋 JSON 数据文件
    participant 工具 as 🔄 html2docx 转换工具
    participant Word as 📑 Word 文档

    rect rgb(235, 245, 255)
    Note right of 用户: ① 制作模板
    用户->>编辑器: 打开编辑器
    用户->>编辑器: 设计表格布局
    用户->>编辑器: 插入占位符 {{字段名}}
    用户->>编辑器: 标记循环行（批量数据）
    用户->>编辑器: 预览效果（可选）
    编辑器-->>用户: 确认模板 OK
    用户->>编辑器: 导出模板
    编辑器->>模板: 保存 .html 文件
    end

    rect rgb(255, 245, 235)
    Note right of 用户: ② 准备数据
    用户->>数据: 编写 JSON 数据文件
    Note over 数据: 字段名对应模板中的占位符
    end

    rect rgb(235, 255, 240)
    Note right of 用户: ③ 生成文档
    用户->>工具: 选择模板 + 数据文件，运行转换
    工具->>模板: 读取模板
    工具->>数据: 读取数据
    工具->>Word: 自动填充数据并生成 DOCX
    Word-->>用户: ✅ 得到最终 Word 文档
    end
Loading

完整工作流

整个工具链的使用流程分为 4 步：

步骤 1：创建/编辑模板（template-editor）

打开可视化模板编辑器：

cd template-editor

# 开发模式（浏览器预览）
npm run dev:react

# 或 Electron 桌面应用模式
npm run dev

编辑器操作说明

布局结构（三栏）：

┌─────────────────────────────────────────────────┐
│  工具栏：新建 / 打开 / 保存 / 导出 / 插入占位符  │
├──────────┬─────────────────────┬────────────────┤
│  组件面板 │    编辑画布          │   属性面板     │
│  · 表格   │   （所见即所得编辑）  │  · 表格信息    │
│  · 标题   │                    │  · 循环行设置   │
│  · 段落   │                    │  · 列宽配置     │
└──────────┴─────────────────────┴────────────────┘

基本操作：

  • 点击左侧组件面板的「表格」「标题」「段落」按钮，插入到编辑器
  • 在编辑器中直接编辑内容，像用 Word 一样操作
  • 表格支持：增删行列、合并单元格、切换表头、调整列宽

插入占位符（{{key}}）：

  • 方式一：点击工具栏「🏷️ 插入占位符」，输入字段名
  • 方式二：直接在单元格中输入 {{fieldName}}，会自动高亮为蓝色标签

设置循环行（{{#each}}）：

  1. 点击表格中的数据行（非表头行）
  2. 在右侧属性面板中点击「设为循环行」
  3. 输入列表字段名（如 employees、items）
  4. 该行会变为黄色高亮，导出时自动生成 {{#each employees}}...{{/each}}

预览渲染：

  1. 准备一个 JSON 数据文件（见 html2docx/templates/employee_data.json 示例）
  2. 点击工具栏「👁️ 预览」按钮
  3. 选择 JSON 文件，实时查看数据渲染效果

保存/导出：

  • 「保存」— 保存为 .html 文件（可重新打开编辑）
  • 「导出」— 导出干净的 .html 模板（供 html2docx 工具使用）

导出的 HTML 模板示例

编辑器导出的 HTML 文件包含完整的模板语法：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>Template</title>
    <style>/* 样式 */</style>
</head>
<body>
    <h1>{{title}}</h1>
    <table>
        <colgroup>
            <col style="width: 20%;">
            <col style="width: 30%;">
            <col style="width: 50%;">
        </colgroup>
        <thead>
            <tr><th>编号</th><th>姓名</th><th>部门</th></tr>
        </thead>
        <tbody>
            {{#each employees}}
            <tr><td>{{id}}</td><td>{{name}}</td><td>{{dept}}</td></tr>
            {{/each}}
        </tbody>
    </table>
</body>
</html>

步骤 2：准备数据文件

创建 JSON 数据文件，字段名与模板中的占位符对应：

{
    "title": "员工信息一览表",
    "totalCount": 8,
    "updateDate": "2026-03-24",
    "employees": [
        {"id": "001", "name": "张三", "dept": "技术部", "role": "工程师", "joinDate": "2022-03-15", "status": "在职"},
        {"id": "002", "name": "李四", "dept": "产品部", "role": "产品经理", "joinDate": "2021-07-20", "status": "在职"}
    ]
}

模板语法说明：

语法 说明 示例
{{key}} 单值替换 {{title}} → "员工信息一览表"
{{obj.key}} 嵌套属性访问 {{user.name}} → "张三"
{{#each list}}...{{/each}} 循环渲染 遍历 employees 数组，每项生成一行

💡 也可以不使用模板编辑器，直接手写 HTML 模板文件，效果一样。

步骤 3：渲染模板（可选验证）

使用测试脚本验证模板渲染效果：

cd html2docx

# 使用默认模板和数据测试
python test_template.py

# 指定自定义模板和数据
python test_template.py -t my_template.html -d my_data.json

# 仅预览渲染后的 HTML（不转 DOCX）
python test_template.py --preview

测试脚本会：

  1. 加载模板和数据
  2. 检查是否有未替换的占位符
  3. 统计渲染的表格行数
  4. 可选：转换并输出 DOCX 文件

步骤 4：转换为 DOCX

cd html2docx

# 模板模式：用数据渲染模板并直接输出 DOCX
python html2docx.py template.html --data data.json -o output.docx

# 保留渲染后的 HTML（用于调试）
python html2docx.py template.html --data data.json -o output.docx --keep-html

高级用法：

# 普通模式：直接转换 HTML 到 DOCX（不涉及模板）
python html2docx.py report.html -o report.docx

# 批量转换目录
python html2docx.py ./html_files -o ./docx_output

# 使用自定义样式模板（控制默认字体、页边距等）
python html2docx.py report.html --reference-doc my_styles.docx

# 预览模式（不实际转换）
python html2docx.py ./html_files --dry-run

# 生成默认样式模板（用 Word 打开后可自定义）
python html2docx.py --init-reference

项目结构

html_template_tool/
├── README.md                          # 本文档
├── html2docx/                         # HTML 转 DOCX 工具
│   ├── html2docx.py                   # 核心转换脚本
│   ├── template_engine.py             # 模板渲染引擎
│   ├── test_template.py               # 模板测试脚本
│   ├── requirements.txt               # Python 依赖
│   ├── reference.docx                 # 默认样式模板
│   └── templates/                     # 示例模板和数据
│       ├── employee_table.html        # 员工信息表模板
│       └── employee_data.json         # 示例数据
├── template-editor/                   # 可视化模板编辑器
│   ├── package.json                   # Node.js 依赖
│   ├── vite.config.js                 # Vite 配置
│   ├── index.html                     # HTML 入口
│   ├── electron/                      # Electron 主进程
│   │   ├── main.js                    # 窗口管理 + 文件对话框
│   │   └── preload.js                 # IPC 通信桥接
│   ├── src/                           # React 源码
│   │   ├── main.jsx                   # React 入口
│   │   ├── App.jsx                    # 主布局
│   │   ├── styles.css                 # 全局样式
│   │   ├── components/                # React 组件
│   │   │   ├── Toolbar.jsx            # 工具栏
│   │   │   ├── ComponentPanel.jsx     # 左侧组件面板
│   │   │   ├── Editor.jsx             # TipTap 编辑器
│   │   │   ├── PropertyPanel.jsx      # 右侧属性面板
│   │   │   ├── PreviewDialog.jsx      # 预览弹窗
│   │   │   └── StatusBar.jsx          # 状态栏
│   │   ├── extensions/                # TipTap 扩展
│   │   │   ├── PlaceholderMark.js     # 占位符高亮标记
│   │   │   └── LoopRowMark.js         # 循环行扩展
│   │   └── utils/                     # 工具函数
│   │       └── htmlExporter.js        # HTML 导出器
│   └── public/                        # 静态资源
│       └── favicon.svg

打包为桌面应用

cd template-editor
npm run build

生成的安装包在 release/ 目录下。

依赖要求

html2docx

template-editor

  • Node.js ≥ 18
  • npm ≥ 8

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages