本文记录了一个真实项目的完整落地过程:后端用 poi-tl 根据 Word 模板渲染数据,前端用 Vue3 提供可视化配置面板,做到「改配置 → 实时生成 → 页面直接预览真实 Word」。这里是我之前工作中遇到的前端需要显示动态的word,具体的数据,其实是前端通过各种操作配置出来的,然后后端再重新拼接这些配置的数据。这里我使用json的方式打包实现了。
一、背景与目标
日常工作中经常需要生成格式固定的 Word 报表(通报函、统计月报等)。传统做法要么是手工复制粘贴,要么是后端写死数据生成文件------前者效率低,后者不灵活。
我们要实现的目标:
- 后端基于 poi-tl 模板引擎,用
{{}}占位符填充数据; - 前端提供表单配置 + JSON 配置两种方式,修改后一键重新生成;
- 页面直接预览真实的 Word 文件,而不是前端伪造的静态卡片;
- Word 中图表、表格要有真实数据和样式;
- 提供默认模板下载,模板里的占位符和配置项一一对应。
最终效果:打开页面 → 左侧是 Word 文档的真实渲染,右侧是配置面板 → 改一个标题或图表数据 → 点「应用配置并重新渲染」→ 左侧文档立即更新。
二、技术栈
| 层 | 技术 | 版本 |
|---|---|---|
| 后端 | Spring Boot | 2.4.8 |
| 模板引擎 | poi-tl | 1.8.2 |
| 表格/图表底层 | Apache POI | 4.x(poi-tl 依赖) |
| 前端 | Vue3 + Vite | Vue 3.5 / Vite 6 |
| Word 预览 | docx-preview | 0.4.1 |
| 图表 | ECharts | 5.x(按需引入) |
| 运行环境 | JDK 17 + Maven 3.6 + Node 23 | --- |
三、整体设计
3.1 数据流
scss
用户在表单/JSON 中修改配置
│
▼
前端离屏用 ECharts 渲染 5 组图表 → 导出 PNG base64
│
▼ POST /poitl/preview.do (配置 JSON + chartImages)
后端按配置构建渲染数据 → poi-tl 渲染模板 → 输出 docx 字节流
│
▼
前端拿到 Blob → renderAsync() 渲染真实 Word → 页面展示
3.2 模板占位符约定
poi-tl 通过占位符前缀区分内容类型:
| 占位符 | 含义 | 对应配置项 |
|---|---|---|
{{title}} |
普通文本 | title |
{{typeContent}} |
带样式文本 | typeContent |
{{@picture}} |
图片 | picture |
{{#showTable}} |
表格(循环) | showTable |
{{*numList}} |
有序/无序列表 | numList |
{{@speedLine}} 等 5 个 |
图表图片 | charts + chartImages |
注意:
@是图片策略,#是表格策略,*是列表策略,不带前缀是文本策略。
3.3 接口设计
| 接口 | 作用 |
|---|---|
GET /poitl/config.do |
获取默认配置 JSON |
GET /poitl/placeholders.do |
获取占位符与配置项对应关系 |
GET /poitl/template.do |
下载含 {{}} 的默认 Word 模板 |
POST /poitl/preview.do |
按配置生成 Word 并返回文件流 |
GET /poitl/download.do |
用默认配置生成 Word |
GET /poitl/generateCharts.do |
服务端生成到本地临时目录 |
服务端口 8090,上下文路径 /report。
四、后端实现
4.1 依赖(pom.xml 关键部分)
xml
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.4.8</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- poi-tl 基于 POI 的 Word 模板引擎 -->
<dependency>
<groupId>com.deepoove</groupId>
<artifactId>poi-tl</artifactId>
<version>1.8.2</version>
</dependency>
<dependency>
<groupId>commons-io</groupId>
<artifactId>commons-io</artifactId>
<version>2.6</version>
</dependency>
</dependencies>
4.2 配置 DTO:所有报表数据的载体
前端传来的 JSON 直接反序列化成这个类。用嵌套静态类组织,结构清晰。
java
@Data
public class ReportConfig {
private String title;
private StyledText typeContent;
private PictureConfig picture;
private TableConfig showTable;
private ListConfig numList;
private List<ChartConfig> charts;
// 图表图片:key=占位符名(labelName),value=base64 PNG
private Map<String, String> chartImages;
@Data
public static class StyledText {
private String color; // 如 cc0000
private String text;
}
@Data
public static class PictureConfig {
private Integer width;
private Integer height;
private String text; // 生成示例图时绘制的文字
private String url; // 填了则用网络图片
}
@Data
public static class TableConfig {
private List<String> headers;
private List<List<String>> rows;
}
@Data
public static class ListConfig {
private String style; // lowerRoman / decimal / bullet ...
private List<String> items;
}
@Data
public static class ChartConfig {
private String labelName; // 对应模板占位符,如 speedLine
private String title;
private String type; // single / multi
private List<String> categories;
private List<SeriesConfig> series;
}
@Data
public static class SeriesConfig {
private String name;
private List<Number> data;
private String comboType; // BAR / LINE / AREA
}
}
对应的完整 JSON 配置示例:
json
{
"title": "2022年月通报函生成报告",
"typeContent": { "color": "cc0000", "text": "这是带样式的内容" },
"picture": { "width": 200, "height": 160, "text": "generate_report" },
"showTable": {
"headers": ["班级", "排名"],
"rows": [["科教1班", "1"], ["幼儿3班", "6"]]
},
"numList": { "style": "lowerRoman", "items": ["排序1", "排序2", "排序3"] },
"charts": [
{
"labelName": "speedLine",
"title": "1-10月份新开工项目数量、投资额增速",
"type": "multi",
"categories": ["1月", "2月", "3月"],
"series": [
{ "name": "项目数量", "data": [-11.02, -19.42, -10.61], "comboType": "LINE" },
{ "name": "投资额", "data": [-12.66, -19.41, -15.16], "comboType": "LINE" }
]
}
],
"chartImages": {
"speedLine": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}
}
4.3 模板渲染封装:渲染 + 表格实线边框
poi-tl 的 MiniTableRenderData 默认生成的表格在部分阅读器里没有实线边框 。解决方案是渲染完成后,拿到 XWPFTemplate 的底层文档,用 POI 的 CTTblBorders 给所有表格补边框。
java
public class OperateWordManage {
public static byte[] generateWordBytes(File templateFile, List<LabelData> contents) {
XWPFTemplate template = null;
try (ByteArrayOutputStream bos = new ByteArrayOutputStream()) {
template = XWPFTemplate.compile(templateFile).render(buildData(contents));
applyTableBorders(template); // 关键:补实线边框
template.write(bos);
return bos.toByteArray();
} catch (Exception e) {
throw new RuntimeException("生成 Word 报表失败", e);
} finally {
if (template != null) template.close();
}
}
/** 给文档中所有表格设置六向实线边框 */
private static void applyTableBorders(XWPFTemplate template) {
for (XWPFTable table : template.getXWPFDocument().getTables()) {
CTTblBorders borders = table.getCTTbl().getTblPr().isSetTblBorders()
? table.getCTTbl().getTblPr().getTblBorders()
: table.getCTTbl().getTblPr().addNewTblBorders();
setBorder(borders.isSetTop() ? borders.getTop() : borders.addNewTop());
setBorder(borders.isSetLeft() ? borders.getLeft() : borders.addNewLeft());
setBorder(borders.isSetBottom() ? borders.getBottom() : borders.addNewBottom());
setBorder(borders.isSetRight() ? borders.getRight() : borders.addNewRight());
setBorder(borders.isSetInsideH()? borders.getInsideH(): borders.addNewInsideH());
setBorder(borders.isSetInsideV()? borders.getInsideV(): borders.addNewInsideV());
}
}
private static void setBorder(CTBorder border) {
border.setVal(STBorder.SINGLE);
border.setSz(BigInteger.valueOf(8)); // 1pt
border.setSpace(BigInteger.ZERO);
border.setColor("000000");
}
/** 把 LabelData 列表转成 poi-tl 的渲染数据 Map */
private static Map<String, Object> buildData(List<LabelData> contents) {
Map<String, Object> data = new HashMap<>(contents.size());
contents.forEach(content -> {
GenerateWord backData = GenerateWordFactory.getBackData(content.getTypeEnum());
data.put(content.getLabelName(), backData.generateWord(content));
});
return data;
}
}
项目里用工厂 + 策略模式把「数据类型」映射到「渲染策略」,TEXT / PICTURE / TABLE / LIST / CHART 各自一个实现类,通过 @PostConstruct 注册到工厂。新增内容类型时只需加一个实现类,不用改渲染主流程。
4.4 Service 核心:双模板策略
这里有一个重要设计:准备两份模板。
demo_template.docx:图表位置放的是 Word 原生图表对象(可编辑,但浏览器预览插件不支持);demo_template_img.docx:把原生图表占位符替换为图片占位符{{@xxx}},用于前端传图片的场景。
java
@Service
public class ApachePoitlServiceImpl implements ApachePoitlService {
private static final String TEMPLATE_PATH = "static/template/demo_template.docx";
private static final String IMAGE_TEMPLATE_PATH = "static/template/demo_template_img.docx";
@Override
public byte[] generateReportBytes(ReportConfig config) {
Map<String, String> chartImages = config == null ? null : config.getChartImages();
// 前端传了图表图片 → 用图片模板;否则用原生图表模板
if (chartImages != null && !chartImages.isEmpty()) {
return OperateWordManage.generateWordBytes(
loadTemplate(IMAGE_TEMPLATE_PATH), buildImageContents(config));
}
return OperateWordManage.generateWordBytes(loadTemplate(), buildContents(config));
}
/** 过滤掉 CHART 类型,改为把 base64 图片按占位符写入 */
private List<LabelData> buildImageContents(ReportConfig config) {
List<LabelData> generates = new ArrayList<>();
for (LabelData data : buildContents(config)) {
if (data.getTypeEnum() != WordContentTypeEnum.CHART) generates.add(data);
}
Map<String, String> images = config.getChartImages();
if (config.getCharts() != null) {
for (ReportConfig.ChartConfig chartConfig : config.getCharts()) {
String label = chartConfig.getLabelName();
if (label == null || !images.containsKey(label)) continue;
PictureContentData picture = new PictureContentData();
picture.setWidth(560).setHeight(300)
.setPicType(PicTypeEnum.PNG)
.setFile(decodeImageFile(images.get(label), label))
.setLabelName(label)
.setTypeEnum(WordContentTypeEnum.PICTURE);
generates.add(picture);
}
}
return generates;
}
/** base64(含 data:image/png;base64, 前缀)转成临时图片文件 */
private File decodeImageFile(String base64, String labelName) {
String data = base64.trim();
int comma = data.indexOf(',');
if (data.startsWith("data:") && comma > 0) data = data.substring(comma + 1);
byte[] bytes = Base64.getDecoder().decode(data);
File image = File.createTempFile("chart_" + labelName + "_", ".png");
Files.write(image.toPath(), bytes);
image.deleteOnExit();
return image;
}
/** jar 内的模板不能直接 getFile(),必须复制成临时文件 */
private File loadTemplate(String path) {
try (InputStream in = new ClassPathResource(path).getInputStream()) {
File temp = File.createTempFile("generate_report_template_", ".docx");
Files.copy(in, temp.toPath(), StandardCopyOption.REPLACE_EXISTING);
temp.deleteOnExit();
return temp;
} catch (IOException e) {
throw new RuntimeException("加载 Word 模板失败", e);
}
}
}
列表样式映射(把前端字符串映射成 poi-tl 常量):
java
private Pair<STNumberFormat.Enum, String> resolveListStyle(String style) {
if (style == null) return NumbericRenderData.FMT_LOWER_ROMAN;
switch (style) {
case "bullet": return NumbericRenderData.FMT_BULLET;
case "decimal": return NumbericRenderData.FMT_DECIMAL;
case "lowerLetter": return NumbericRenderData.FMT_LOWER_LETTER;
case "upperLetter": return NumbericRenderData.FMT_UPPER_LETTER;
case "upperRoman": return NumbericRenderData.FMT_UPPER_ROMAN;
default: return NumbericRenderData.FMT_LOWER_ROMAN;
}
}
4.5 Controller:文件流下载
统一的文件写出方法,注意文件名要 URL 编码,否则中文名会乱码。
java
@RestController
@RequestMapping("/poitl")
public class ApachePoitlController {
@Autowired private ApachePoitlService poitlService;
@GetMapping("/config.do")
public ReportConfig config() { return poitlService.getDefaultConfig(); }
@GetMapping("/placeholders.do")
public List<Map<String, String>> placeholders() { return poitlService.getPlaceholders(); }
@GetMapping("/template.do")
public void template(HttpServletResponse response) throws IOException {
byte[] bytes = poitlService.getDefaultTemplate();
String fileName = URLEncoder.encode("报表默认模板.docx", "UTF-8");
response.setContentType(
"application/vnd.openxmlformats-officedocument.wordprocessingml.document");
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + fileName);
response.setContentLength(bytes.length);
response.getOutputStream().write(bytes);
response.getOutputStream().flush();
}
@PostMapping("/preview.do")
public void preview(@RequestBody ReportConfig config, HttpServletResponse response) throws IOException {
writeDocx(response, poitlService.generateReportBytes(config));
}
private void writeDocx(HttpServletResponse response, byte[] bytes) throws IOException {
String fileName = URLEncoder.encode("月度通报函生成报告.docx", "UTF-8");
response.setContentType(
"application/vnd.openxmlformats-officedocument.wordprocessingml.document");
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + fileName);
response.setContentLength(bytes.length);
response.getOutputStream().write(bytes);
response.getOutputStream().flush();
}
}
跨域配置(前端 dev server 在 5173,后端在 8090):
java
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowedOriginPatterns("*")
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("*")
.maxAge(3600);
}
}
五、前端实现
5.1 项目结构与依赖
css
frontend/
├── index.html
├── package.json
├── vite.config.js
└── src/
├── main.js
├── App.vue
└── style.css
json
{
"scripts": {
"dev": "vite --host :: --port 5173",
"build": "vite build"
},
"dependencies": {
"docx-preview": "^0.4.1",
"echarts": "^5.x",
"vue": "^3.5.13"
},
"devDependencies": {
"@vitejs/plugin-vue": "^5.2.1",
"vite": "^6.0.7"
}
}
"--host ::"让 Vite 同时监听 IPv4/IPv6。若只写0.0.0.0,浏览器访问localhost可能优先走 IPv6 而命中别的程序。
Vite 代理,避免开发时跨域:
js
export default defineConfig({
plugins: [vue()],
server: {
port: 5173,
proxy: {
'/report': { target: 'http://localhost:8090', changeOrigin: true }
}
}
})
5.2 核心:离屏 ECharts 生成图表图片
页面只保留 Word 预览,不展示图表 div。但 Word 里要有真实图表,所以离屏渲染:临时创建一个不在视口内的 div,渲染完导出 PNG,随即销毁。
js
import * as echarts from 'echarts/core'
import { BarChart, LineChart } from 'echarts/charts'
import { GridComponent, LegendComponent, TitleComponent, TooltipComponent } from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'
echarts.use([BarChart, LineChart, GridComponent, LegendComponent,
TitleComponent, TooltipComponent, CanvasRenderer])
function buildChartImages() {
const images = {}
const host = document.createElement('div')
host.style.cssText = 'position:absolute;left:-99999px;top:0;width:560px;height:300px;'
document.body.appendChild(host)
try {
draft.charts.forEach(chart => {
if (!chart.labelName) return
const instance = echarts.init(host)
instance.setOption(chartOption(chart), { notMerge: true, lazyUpdate: false })
images[chart.labelName] = instance.getDataURL({
type: 'png',
pixelRatio: 2,
backgroundColor: '#ffffff',
excludeComponents: ['tooltip']
})
instance.dispose()
})
} finally {
document.body.removeChild(host)
}
return images
}
图表配置里 animation: false 是关键(否则导出的是动画刚开始的空白图):
js
function chartOption(chart) {
const category = (chart.comboType || '').toUpperCase()
const type = category === 'BAR' ? 'bar' : 'line'
const isSingle = chart.type === 'single'
return {
animation: false, // 必须关闭,否则 getDataURL 拿到空图
title: { text: chart.title, left: 'center' },
tooltip: { trigger: 'axis' },
legend: { bottom: 0 },
grid: { left: 52, right: 16, top: 34, bottom: 50 },
xAxis: { type: 'category', data: splitList(chart.categoriesText) },
yAxis: { type: 'value' },
series: chart.series.map(s => {
const item = {
name: s.name,
type,
data: splitList(s.dataText).map(Number)
}
if (category === 'AREA' || (isSingle && !category)) item.areaStyle = {}
return item
})
}
}
5.3 核心:提交配置 + renderAsync 预览真实 Word
js
async function renderDocx(cfg) {
previewLoading.value = true
try {
// 1. 配置 + 图表图片一起提交
const payload = { ...cfg, chartImages: buildChartImages() }
const response = await fetch(`${API_BASE}/report/poitl/preview.do`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload)
})
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const blob = await response.blob()
// 2. 用 docx-preview 渲染真实 Word
previewEl.value.innerHTML = ''
await renderAsync(blob, previewEl.value, undefined, {
className: 'docx-body',
inWrapper: false,
ignoreWidth: false,
ignoreHeight: false,
breakPages: true
})
currentBlob.value = blob
previewed.value = true
} finally {
previewLoading.value = false
}
}
5.4 表单配置与 JSON 配置双向同步
用 reactive 维护一份草稿 draft,表单直接 v-model 绑定;切换到 JSON 标签时序列化,应用 JSON 时反序列化回草稿。图表数据(分类、系列)在草稿里用逗号分隔的字符串,提交时转成数组。
js
function configToDraft(cfg) {
draft.title = cfg.title || ''
draft.typeColor = cfg.typeContent?.color || ''
draft.tableHeaders = [...(cfg.showTable?.headers || [])]
draft.tableRows = (cfg.showTable?.rows || []).map(r => [...r])
draft.charts = (cfg.charts || []).map(c => ({
labelName: c.labelName,
title: c.title,
type: c.type,
categoriesText: (c.categories || []).join(', '),
series: (c.series || []).map(s => ({
name: s.name,
dataText: (s.data || []).join(', '),
comboType: s.comboType || ''
}))
}))
}
function draftToConfig() {
return {
title: draft.title,
typeContent: { color: draft.typeColor, text: draft.typeText },
showTable: { headers: [...draft.tableHeaders], rows: draft.tableRows.map(r => [...r]) },
charts: draft.charts.map(c => ({
labelName: c.labelName,
title: c.title,
type: c.type,
categories: splitList(c.categoriesText),
series: c.series.map(s => ({
name: s.name,
data: splitList(s.dataText).map(Number),
comboType: s.comboType || null
}))
}))
}
}
界面上三个标签页:表单配置、JSON 配置、默认模板(展示占位符对应表并提供模板下载)。
六、运行方式
bash
# 后端
cd generate_report
mvn -DskipTests package
java -jar target/generate_report-0.0.1-SNAPSHOT.jar
# 服务地址 http://localhost:8090/report
# 前端
cd frontend
npm install --registry=https://registry.npmjs.org
npm run dev
# 页面地址 http://localhost:5173
若公司 npm 镜像需要鉴权报 E401,可临时指定官方源:
npm install --registry=https://registry.npmjs.org。
七、总结
这个方案的核心是把「Word 模板渲染」和「前端可视化配置」解耦:
- 后端只关心「给我配置,还你 docx」,通过双模板策略兼顾原生图表与浏览器预览;
- 前端只关心「配置怎么来、生成的 Word 怎么展示」,用离屏 ECharts 解决图表数据问题,用
docx-preview展示真实文档; - JSON 配置作为前后端契约,既方便程序调用,也方便人工微调。
对于需要生成固定格式 Word 报表的场景,这套「模板 + 配置 + 在线预览」的模式可以直接复用。如果你也在做类似需求,希望文中的踩坑记录能帮你少走弯路。
根据大佬的逻辑,新增vue3代码以及补充更多的java代码 github.com/xiaoxcx/gen...
预览结果:
