Spring Boot + poi-tl + Vue3 实现可配置的 Word 报表生成与在线预览

本文记录了一个真实项目的完整落地过程:后端用 poi-tl 根据 Word 模板渲染数据,前端用 Vue3 提供可视化配置面板,做到「改配置 → 实时生成 → 页面直接预览真实 Word」。这里是我之前工作中遇到的前端需要显示动态的word,具体的数据,其实是前端通过各种操作配置出来的,然后后端再重新拼接这些配置的数据。这里我使用json的方式打包实现了。

一、背景与目标

日常工作中经常需要生成格式固定的 Word 报表(通报函、统计月报等)。传统做法要么是手工复制粘贴,要么是后端写死数据生成文件------前者效率低,后者不灵活。

我们要实现的目标:

  1. 后端基于 poi-tl 模板引擎,用 {{}} 占位符填充数据;
  2. 前端提供表单配置 + JSON 配置两种方式,修改后一键重新生成;
  3. 页面直接预览真实的 Word 文件,而不是前端伪造的静态卡片;
  4. Word 中图表、表格要有真实数据和样式;
  5. 提供默认模板下载,模板里的占位符和配置项一一对应。

最终效果:打开页面 → 左侧是 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...

预览结果:

相关推荐
小稀土1232 小时前
一站式 DevOps 解决方案怎么选?流水线、制品库到效能度量落地路径
后端
程序员cxuan2 小时前
REA 靠边站,逆向圈又一新王诞生了
人工智能·后端·程序员
Lansonli2 小时前
大数据Spark(九十):Spark广播变量与累加器详解
服务器·前端·ajax
nice_lcj5202 小时前
【从零理解计算机网络 · 03】IP 与端口:数据怎么找到机器,又怎么找到进程
后端·网络协议·计算机网络·面试·ip地址·端口·127.0.0.1
SEO_juper3 小时前
Node.js 全站 SEO 体检报告生成器:一次查完标题、描述、canonical、H1、图片
开发语言·前端·node.js·html·bash
NoteDeep 深度笔记4 小时前
DOM 被改乱了怎么办?Notedeep 编辑器的 normalize 设计
前端·javascript·编辑器
zhanlang02174 小时前
HTML 零基础入门到企业实战【第七章 7.2】form 标签属性:action、method、name、target 详解
前端·html
一条Go4 小时前
Pod 终端与日志:为什么浏览器建连要先换一张 60 秒的票
后端·架构·github
涛涛ing4 小时前
面试了20个前端,我发现高薪的都不怎么拼“底层原理”
前端