XLSX 模板导出工具

什么是 XLSX 模板导出？

XLSX 模板导出是一个基于 xlsx-template 的 Excel 文档生成工具，它允许用户使用预先设计好的 Excel 模板，结合 Excel 或 CSV 数据源，批量生成个性化的 Excel 文档。

核心价值

1. 批量生成：一次操作生成多份个性化 Excel 文档
2. 模板复用：设计一次模板，永久使用
3. 格式保真：保留 Excel 原生格式、样式和公式
4. 简单易用：无需编程知识即可上手

典型应用场景

• 报表生成：批量生成财务报表、销售报表
• 数据导出：批量生成用户数据、产品数据
• 表单填写：批量生成合同、协议、申请表
• 数据报告：批量生成数据分析报告、统计报表

技术基础

本工具使用 xlsx-template 作为核心渲染引擎，这是目前成熟的 JavaScript Excel 模板库之一，支持：

• 变量替换
• 数组展开
• 表格生成
• 图片插入

使用方法

1. 准备数据

1.1 下载数据模板

点击「下载模板」按钮，选择 CSV 或 Excel 格式，下载包含示例字段的数据模板。

1.2 填写数据

在模板中填入你的数据，确保列名与你将在模板中使用的字段名一致。

2. 上传数据文件

点击「上传数据文件」，选择你准备好的 CSV 或 Excel 文件。

系统会自动检测文件中的字段并显示。

3. 设置忽略行数

如果你的数据文件包含标题行或其他不需要的行，可以设置忽略前 N 行。

4. 准备 Excel 模板

4.1 设计模板

在 Excel 中设计你的模板，使用 ${字段名} 作为占位符。

例如：

• 简单变量：${name}
• 数组展开：${items}
• 表格生成：${table:items.name}

4.2 上传模板

点击「上传 XLSX 模板」，选择你设计好的 Excel 模板文件。

5. 设置输出文件名

5.1 文件名模板

使用 {字段名} 作为占位符，例如 {name}-{日期}。

5.2 重名处理策略

• 追加序号：在重名文件后添加 (1), (2) 等序号
• 行号前缀：在文件名前添加 001-, 002- 等行号前缀

5.3 预览文件名

系统会根据前 3 行数据预览生成的文件名。

6. 渲染与下载

6.1 渲染文档

点击「渲染」按钮，系统会为每一行数据生成一份 Excel 文档。

6.2 下载结果

• 单文件：直接下载该文件
• 多文件：打包成 ZIP 下载

术

核心依赖

exceljs

• 用途：XLSX 模板渲染引擎，读取带占位符的 Excel 模板文件并填充数据
• 官网：https://github.com/exceljs/exceljs
• 版本：^4.4.0
• 注意：通过全局脚本 window.ExcelJS 加载（非 ES Module import），需要提前在 HTML 中引入

xlsx

• 用途：SheetJS 社区版，用于读取用户上传的 Excel 数据文件
• 官网：https://sheetjs.com/
• 版本：^0.18.5

papaparse

• 用途：高性能 CSV 解析库
• 官网：https://www.papaparse.com/
• 版本：^5.5.3

jszip

• 用途：批量导出时将多个生成的 XLSX 文件打包为 ZIP
• 官网：https://stuk.github.io/jszip/
• 版本：^3.10.1

file-saver

• 用途：触发浏览器文件下载
• 官网：https://github.com/eligrey/FileSaver.js
• 版本：^2.0.5

工作原理

用户数据 (CSV / Excel)
       ↓
  数据解析层 (papaparse / xlsx)
       ↓
  JSON 数据数组 [{行1字段...}, {行2字段...}, ...]
       ↓
  模板渲染层 (exceljs — workbook.xlsx.load + 逐个Sheet/Row填充)
       ↓
  XLSX 文件生成 (Buffer)
       ↓
  文件下载 (file-saver) 或 ZIP 打包 (jszip)

占位符语法

模板中使用单层花括号 {field_name} 标记占位符：

// 文件名模板验证逻辑 — 支持 {字段名} 格式
function validateFilenameTemplate(template: string): { valid: boolean; error?: string } {
  // 检查花括号匹配、空占位符、非法字符
  const re = /\{([^}]+)\}/g
}

• {name} → 替换为数据行中 name 字段的值
• {城市} → 支持中文字段名
• 仅支持字母、数字、下划线和中文字段名

关键实现

ExcelJS 工作簿渲染

// 使用 exceljs 加载模板并逐行填充
declare global {
  interface Window {
    ExcelJS: typeof import('exceljs')
  }
}

// 渲染流程：load template → for each data row → clone template sheet → fill cells → write buffer

文件名去重

// 多行数据生成同名文件时自动追加序号
function sanitizeFilename(name: string): string {
  return name.replace(/[\\/:*?"<>|]/g, '-').replace(/\s+/g, ' ').trim() || '未命名'
}

文件大小限制

• 数据文件：建议不超过 10MB
• 模板文件：建议不超过 5MB

已知限制

1. 依赖浏览器全局 window.ExcelJS 对象，需确保 public/exceljs.min.js 已正确加载
2. 复杂图表和样式可能无法完全保留，取决于 exceljs 对模板特性的支持程度