1. 项目概述当模板遇到动态数据在后台开发或者数据报表生成的日常里我们经常遇到一个经典场景手里有一个设计好的Word或Excel模板需要把数据库里查出来的一批动态数据严丝合缝地填进去特别是当数据量不确定需要动态生成表格行的时候。手动复制粘贴效率低下且容易出错。用传统的Apache POI硬编码那简直是噩梦一个单元格一个单元格地设置样式和值代码冗长维护起来想哭。这时候POI-tlPOI template language就像是一把瑞士军刀。它不是一个全新的文档处理库而是基于Apache POI的一个“增强包”或“语法糖”。它的核心思想是“声明式”编程你在Word或Excel模板里用特定的标签比如{{var}}、{{#list}}定义好占位符和循环区域然后在代码里你只需要准备好一个数据模型Map或对象POI-tl引擎就会自动帮你完成渲染。你不再需要关心第几行第几列只需要关心数据和模板的对应关系。而“动态生成表格”尤其是基于列表数据动态添加行是POI-tl解决得最漂亮的痛点之一。想象一下你有一个员工信息表模板表头是固定的但员工数量每次导出都不同。用POI-tl你只需要在模板里标记好循环区域代码里传入一个ListEmployee它就能自动生成对应行数的表格并且完美继承模板里定义的样式字体、颜色、边框、对齐方式等。这对于生成合同明细、成绩单、统计报表等文档来说效率和代码可读性都是质的飞跃。本文将深入拆解如何使用POI-tl实现动态表格并分享从官方文档到实战踩坑的全过程经验。2. 核心思路与模板设计哲学2.1 从“代码驱动”到“模板驱动”的范式转变在接触POI-tl之前我们生成Word文档的思维是“代码驱动”的。流程大致是用POI创建一个空的XWPFDocument对象然后开始用代码“画”文档——创建段落、创建表格、创建行、创建单元格、设置单元格文本和样式。这种方式的控制力极强但灵活性极差业务逻辑数据获取和视图逻辑文档渲染严重耦合。一旦模板样式需要调整开发人员就必须修改代码重新测试整个过程非常笨重。POI-tl引入了“模板驱动”的思想。它的工作流分为清晰的两步模板制作由非技术人员如产品经理、运营或前端人员在Microsoft Office或WPS中使用他们熟悉的工具设计出最终想要的文档样式并在需要插入动态数据的地方使用POI-tl约定的标签进行标记。这个.docx文件就是你的模板。数据渲染开发人员在代码中专注于构建一个结构化的数据模型通常是一个MapString, Object然后调用POI-tl的API指定模板文件路径和数据模型引擎会自动完成渲染输出最终的文档。这样做的好处是巨大的职责分离样式归模板数据归代码。UI调整无需发版。维护性高模板是独立的文件修改直观。代码只需处理数据聚合。复用性强同一个模板搭配不同的数据模型可以生成无数份文档。2.2 动态表格的两种实现模式对于动态表格POI-tl主要提供了两种标签模式对应不同的应用场景区块对循环{{#list}}...{{/list}}这是最常用、最强大的方式。它在模板中定义一个“区块”这个区块通常是一个表格行w:tr。引擎会遍历你传入的List数据为每一条数据复制这个区块包括其所有样式和子标签并进行渲染。这是实现“动态增加行”的核心机制。表格渲染{{*table}}这是一个更高级的特性。它允许你直接传入一个ListListObject二维数组或一个TableRenderData对象POI-tl会在标签位置自动生成一个完整的表格并可以应用预定义的样式。这种方式更适用于数据源本身就是二维结构且对表格样式有统一要求的场景。本整理将重点聚焦于最常用的区块对循环模式因为它在处理业务数据如对象列表时最直观也最能体现模板驱动的优势。2.3 模板标签的精准定位理解标签在文档XML结构中的位置至关重要这直接决定了渲染是否成功。一个.docx文件本质上是一个ZIP压缩包解压后可以看到其XML结构。对于Word来说一个表格w:tbl由若干行w:tr组成一行由若干单元格w:tc组成单元格内又有段落w:p和文本运行w:r、w:t。关键原则你的循环标签{{#list}}和{{/list}}必须完整地包裹住一个或多个完整的文档元素节点。正确示例{{#list employees}}和{{/list}}分别位于一个表格行的开始w:tr之前和结束之后。这样引擎就知道要复制整个w:tr。错误示例标签被拆散在不同的XML节点中或者只包裹了单元格w:tc而不是行w:tr这会导致模板解析失败生成混乱的文档。实操心得最简单的检查方法是在Word里打开“显示编辑标记”Word中快捷键Ctrl*或CtrlShift8。你会看到段落标记和表格框线。确保你的标签放在一个完整的表格行内并且标签前后没有多余的段落标记。最好为循环行单独设计一行避免与表头行或其它静态行产生结构嵌套。3. 从零到一一个完整的动态表格生成实例让我们通过一个具体的例子——“员工信息导出”——来贯穿整个流程。假设我们需要导出某个部门的所有员工信息包括姓名、工号、部门和入职日期。3.1 第一步制作Word模板我们在Word中创建一个包含表头和一行数据行的表格。姓名工号部门入职日期{{name}}{{workId}}{{dept}}{{#joinDate}}{{/joinDate}}注意第一行是表头第二行是我们的模板行。现在我们需要将第二行设置为循环区块。将光标放在第二行数据行的第一个单元格内的文本{{name}}之前。输入区块开始标签{{#employees}}。这里的employees是我们将在代码中传入的List变量的名称。将光标放在第二行数据行的最后一个单元格之后表格的外面确保不在第三个单元格里。输入区块结束标签{{/employees}}。最终你的模板行看起来应该是这样在显示编辑标记的状态下{{#employees}} ... 整个第二行表格内容 ... {{/employees}}确保{{#employees}}和{{/employees}}这对标签完整地包裹了整个表格行从w:tr到。注意事项日期处理。在模板中我们使用了{{#joinDate}}{{/joinDate}}这对标签来渲染日期。这是POI-tl的语法#和/表示中间是一个可以被渲染的区域POI-tl会根据数据模型中的值类型如java.util.Date自动应用格式化。你也可以使用{{joinDate}}但那样需要你在数据模型中预先格式化成字符串。3.2 第二步准备数据模型Java端在Java代码中我们需要做三件事定义数据对象、组装数据列表、构建POI-tl能识别的数据模型。// 1. 定义员工实体类可使用Lombok简化 Data // Lombok注解生成getter/setter等 public class Employee { private String name; private String workId; private String dept; private Date joinDate; // 构造函数、getter、setter ... } // 2. 在Service或Controller中组装数据和渲染 public void exportEmployeeReport(HttpServletResponse response) throws Exception { // 模拟从数据库查询数据 ListEmployee employeeList new ArrayList(); employeeList.add(new Employee(张三, 1001, 技术部, parseDate(2020-06-01))); employeeList.add(new Employee(李四, 1002, 市场部, parseDate(2019-03-15))); employeeList.add(new Employee(王五, 1003, 技术部, parseDate(2021-08-23))); // ... 可以添加更多 // 3. 构建POI-tl数据模型 MapString, Object dataModel new HashMap(); dataModel.put(employees, employeeList); // 这里的key employees 必须和模板中的 {{#employees}} 对应 // 4. 配置并执行渲染 // 指定模板路径假设模板放在 resources/templates 下 ClassPathResource templateResource new ClassPathResource(templates/employee_template.docx); XWPFTemplate template XWPFTemplate.compile(templateResource.getInputStream()).render(dataModel); // 5. 输出到Http响应流供浏览器下载 response.setContentType(application/vnd.openxmlformats-officedocument.wordprocessingml.document); response.setHeader(Content-Disposition, attachment;filenameemployee_list.docx); template.writeAndClose(response.getOutputStream()); }关键点解析dataModel.put(employees, employeeList)这是连接模板和代码的桥梁。Map的keyemployees必须与模板中的区块标签{{#employees}}的名字完全一致区分大小写。XWPFTemplate.compile(...).render(dataModel)这是核心API。compile方法加载并解析模板文件render方法将数据模型注入模板生成最终文档对象。数据模型中的employeeList里的每个Employee对象在渲染时其属性name,workId等会自动与模板行内的标签{{name}}、{{workId}}等进行匹配并替换。3.3 第三步运行与结果运行上述代码后POI-tl会进行如下操作读取模板发现{{#employees}}标签。获取数据模型中key为employees的值发现它是一个List。对于List中的每一个Employee对象复制一份被{{#employees}}和{{/employees}}包裹的整个表格行。在这个新复制的行里将{{name}}替换为当前员工的name属性值{{workId}}替换为workId以此类推。如果joinDate是Date类型{{#joinDate}}{{/joinDate}}标签会将其渲染为默认的日期格式。将渲染好的所有新行插入到模板中标签所在的位置。最终生成的Word文档将包含一个表格第一行是原始表头后续行是动态生成的员工数据行行数等于employeeList.size()。4. 进阶技巧与深度配置4.1 样式与格式的继承与控制POI-tl最强大的特性之一就是完美的样式继承。模板行里设置的所有格式——字体、大小、颜色、加粗、单元格背景色、边框、合并单元格、行高、列宽——都会在每一行新生成的动态行中保留。但是有时我们需要更精细的控制条件格式化例如对入职超过3年的员工姓名加粗显示。动态计算在表格中增加一列“司龄”根据入职日期计算。这可以通过自定义RenderPolicy渲染策略来实现。POI-tl允许你为特定的标签注册一个自定义的渲染器。// 示例自定义一个渲染策略为特定条件的文本加粗 public class BoldIfSeniorPolicy implements RenderPolicy { Override public void render(ElementTemplate eleTemplate, Object data, XWPFTemplate template) { // eleTemplate是模板标签元素 // data是数据模型中对应此标签的值 // template是当前文档模板 if (data null) return; // 假设传入的数据是Employee对象 Employee emp (Employee) data; // 获取标签所在的Run对象用于设置样式 Run run eleTemplate.getRun(); // 判断是否老员工假设超过3年 long threeYearsAgo System.currentTimeMillis() - (3L * 365 * 24 * 60 * 60 * 1000); if (emp.getJoinDate().getTime() threeYearsAgo) { // 设置加粗 run.setBold(true); // 也可以设置颜色等 // run.setColor(FF0000); } // 最后还是要设置文本内容 run.setText(emp.getName()); // 这里渲染的是姓名 } } // 在配置中使用自定义策略 Configure config Configure.builder() .bind(name, new BoldIfSeniorPolicy()) // 将模板中的{{name}}标签绑定到自定义策略 .build(); XWPFTemplate template XWPFTemplate.compile(templatePath, config).render(dataModel);踩坑记录自定义RenderPolicy功能强大但需谨慎使用。首先它破坏了“模板驱动”的部分纯粹性将样式逻辑又挪回了代码。其次在RenderPolicy中直接操作底层的Run或Paragraph对象需要你对POI的API有一定了解否则容易导致文档损坏。建议仅在标准标签无法满足复杂需求如单元格内嵌图表、复杂条件格式时才使用。4.2 处理复杂嵌套结构业务数据常常是嵌套的。例如一个部门对象包含一个员工列表。POI-tl同样支持嵌套循环。模板设计部门{{deptName}} {{#deptEmployees}} | {{name}} | {{workId}} | {{#joinDate}}{{/joinDate}} | {{/deptEmployees}}在数据模型中你需要提供一个ListDepartment其中每个Department对象有一个deptName属性和一个ListEmployee deptEmployees属性。POI-tl会先遍历部门列表在每个部门区块内再遍历该部门的员工列表。4.3 图片、列表与超链接的嵌入POI-tl不仅支持文本和表格还支持丰富的元素。图片使用{{picture}}标签。数据模型中需要提供一个PictureRenderData对象其中包含图片流、图片类型和尺寸。dataModel.put(logo, new PictureRenderData(120, 120, .png, imageStream));列表使用{{*list}}标签。数据模型中需要提供ListRenderData对象它可以包含多个TextRenderData来定义列表项的样式。超链接使用{{link}}标签。数据模型中需要提供HyperlinkTextRenderData对象包含链接地址和显示文本。这些高级元素的使用让生成的文档不再是单调的表格和文字可以做出非常专业的报告。5. 常见问题排查与性能优化在实际项目中你肯定会遇到各种问题。下面是一个快速排查指南问题现象可能原因解决方案生成的文档中标签{{xxx}}原样显示未被替换。1. 数据模型中的key与模板标签名不匹配。2. 数据模型中该key的值为null。1. 仔细检查拼写和大小写。2. 确保数据模型已正确放入该key-value对。动态表格只生成了一行或行数不对。1.{{#list}}和{{/list}}标签没有完整包裹表格行。2. 传入的数据不是List类型或者是空列表。1. 用Word“显示编辑标记”功能检查标签位置确保它们包裹了整个w:tr。2. 检查Java代码中组装List的逻辑。文档打开报错“文件损坏”。1. 自定义RenderPolicy中错误地操作了文档结构。2. 模板文件本身格式异常如从网页复制粘贴的表格。1. 检查自定义渲染策略的逻辑避免删除或移动关键XML节点。2. 尝试在Word中新建一个简单表格重新制作模板。生成大量数据时内存溢出OOM。一次性渲染的数据行数过多如数万行所有行都保存在内存中的XWPFDocument对象里。1.分页导出业务上支持分页查询和导出。2.流式处理对于极端情况考虑回归低层POI的SXSSFWorkbookExcel或寻找其他流式Word生成方案POI-tl本身不是为流式设计的。日期、数字格式不符合要求。POI-tl的默认格式化可能不满足需求。1. 在数据模型中预先将Date/Number格式化成String再传入。2. 使用{{#joinDate}}{{/joinDate}}配合自定义的RenderPolicy来精细控制格式。单元格合并在动态行中失效。模板行中存在合并单元格但循环复制时合并的属性可能无法正确应用到新行。这是一个已知的复杂情况。解决方案通常更复杂要么避免在循环行中使用合并要么通过自定义RenderPolicy在渲染每行后以编程方式动态设置单元格的合并属性。性能优化建议模板最小化模板文件不宜过大、过于复杂。复杂的样式和大量无关内容会增加解析开销。数据分批对于导出功能务必在业务层实现分页查询。不要试图一次性导出10万条数据到单个Word文档用户体验和系统性能都会很差。通常1000行以内的表格体验是可接受的。缓存Configure对象Configure对象包含了标签绑定、插件等配置。如果配置不变应该将其声明为单例或静态变量避免每次导出都重新创建。复用XWPFTemplate对象不不要这么做。XWPFTemplate对象在write或writeAndClose方法调用后内部状态可能已改变不适合复用。每次导出都应该是compile - render - write - close的完整生命周期。最后再分享一个调试小技巧当你对模板标签的位置不确定时可以将.docx模板文件的后缀改为.zip解压后查看word/document.xml文件。在这个XML文件中搜索你的标签名可以最准确地看到它们所在的XML节点结构这对于解决复杂的渲染问题非常有帮助。不过直接修改这个XML风险很高建议仅作为调试参考修改还是回到Word界面进行。 POI-tl动态表格生成：从模板驱动到Java数据渲染实战
1. 项目概述当模板遇到动态数据在后台开发或者数据报表生成的日常里我们经常遇到一个经典场景手里有一个设计好的Word或Excel模板需要把数据库里查出来的一批动态数据严丝合缝地填进去特别是当数据量不确定需要动态生成表格行的时候。手动复制粘贴效率低下且容易出错。用传统的Apache POI硬编码那简直是噩梦一个单元格一个单元格地设置样式和值代码冗长维护起来想哭。这时候POI-tlPOI template language就像是一把瑞士军刀。它不是一个全新的文档处理库而是基于Apache POI的一个“增强包”或“语法糖”。它的核心思想是“声明式”编程你在Word或Excel模板里用特定的标签比如{{var}}、{{#list}}定义好占位符和循环区域然后在代码里你只需要准备好一个数据模型Map或对象POI-tl引擎就会自动帮你完成渲染。你不再需要关心第几行第几列只需要关心数据和模板的对应关系。而“动态生成表格”尤其是基于列表数据动态添加行是POI-tl解决得最漂亮的痛点之一。想象一下你有一个员工信息表模板表头是固定的但员工数量每次导出都不同。用POI-tl你只需要在模板里标记好循环区域代码里传入一个ListEmployee它就能自动生成对应行数的表格并且完美继承模板里定义的样式字体、颜色、边框、对齐方式等。这对于生成合同明细、成绩单、统计报表等文档来说效率和代码可读性都是质的飞跃。本文将深入拆解如何使用POI-tl实现动态表格并分享从官方文档到实战踩坑的全过程经验。2. 核心思路与模板设计哲学2.1 从“代码驱动”到“模板驱动”的范式转变在接触POI-tl之前我们生成Word文档的思维是“代码驱动”的。流程大致是用POI创建一个空的XWPFDocument对象然后开始用代码“画”文档——创建段落、创建表格、创建行、创建单元格、设置单元格文本和样式。这种方式的控制力极强但灵活性极差业务逻辑数据获取和视图逻辑文档渲染严重耦合。一旦模板样式需要调整开发人员就必须修改代码重新测试整个过程非常笨重。POI-tl引入了“模板驱动”的思想。它的工作流分为清晰的两步模板制作由非技术人员如产品经理、运营或前端人员在Microsoft Office或WPS中使用他们熟悉的工具设计出最终想要的文档样式并在需要插入动态数据的地方使用POI-tl约定的标签进行标记。这个.docx文件就是你的模板。数据渲染开发人员在代码中专注于构建一个结构化的数据模型通常是一个MapString, Object然后调用POI-tl的API指定模板文件路径和数据模型引擎会自动完成渲染输出最终的文档。这样做的好处是巨大的职责分离样式归模板数据归代码。UI调整无需发版。维护性高模板是独立的文件修改直观。代码只需处理数据聚合。复用性强同一个模板搭配不同的数据模型可以生成无数份文档。2.2 动态表格的两种实现模式对于动态表格POI-tl主要提供了两种标签模式对应不同的应用场景区块对循环{{#list}}...{{/list}}这是最常用、最强大的方式。它在模板中定义一个“区块”这个区块通常是一个表格行w:tr。引擎会遍历你传入的List数据为每一条数据复制这个区块包括其所有样式和子标签并进行渲染。这是实现“动态增加行”的核心机制。表格渲染{{*table}}这是一个更高级的特性。它允许你直接传入一个ListListObject二维数组或一个TableRenderData对象POI-tl会在标签位置自动生成一个完整的表格并可以应用预定义的样式。这种方式更适用于数据源本身就是二维结构且对表格样式有统一要求的场景。本整理将重点聚焦于最常用的区块对循环模式因为它在处理业务数据如对象列表时最直观也最能体现模板驱动的优势。2.3 模板标签的精准定位理解标签在文档XML结构中的位置至关重要这直接决定了渲染是否成功。一个.docx文件本质上是一个ZIP压缩包解压后可以看到其XML结构。对于Word来说一个表格w:tbl由若干行w:tr组成一行由若干单元格w:tc组成单元格内又有段落w:p和文本运行w:r、w:t。关键原则你的循环标签{{#list}}和{{/list}}必须完整地包裹住一个或多个完整的文档元素节点。正确示例{{#list employees}}和{{/list}}分别位于一个表格行的开始w:tr之前和结束之后。这样引擎就知道要复制整个w:tr。错误示例标签被拆散在不同的XML节点中或者只包裹了单元格w:tc而不是行w:tr这会导致模板解析失败生成混乱的文档。实操心得最简单的检查方法是在Word里打开“显示编辑标记”Word中快捷键Ctrl*或CtrlShift8。你会看到段落标记和表格框线。确保你的标签放在一个完整的表格行内并且标签前后没有多余的段落标记。最好为循环行单独设计一行避免与表头行或其它静态行产生结构嵌套。3. 从零到一一个完整的动态表格生成实例让我们通过一个具体的例子——“员工信息导出”——来贯穿整个流程。假设我们需要导出某个部门的所有员工信息包括姓名、工号、部门和入职日期。3.1 第一步制作Word模板我们在Word中创建一个包含表头和一行数据行的表格。姓名工号部门入职日期{{name}}{{workId}}{{dept}}{{#joinDate}}{{/joinDate}}注意第一行是表头第二行是我们的模板行。现在我们需要将第二行设置为循环区块。将光标放在第二行数据行的第一个单元格内的文本{{name}}之前。输入区块开始标签{{#employees}}。这里的employees是我们将在代码中传入的List变量的名称。将光标放在第二行数据行的最后一个单元格之后表格的外面确保不在第三个单元格里。输入区块结束标签{{/employees}}。最终你的模板行看起来应该是这样在显示编辑标记的状态下{{#employees}} ... 整个第二行表格内容 ... {{/employees}}确保{{#employees}}和{{/employees}}这对标签完整地包裹了整个表格行从w:tr到。注意事项日期处理。在模板中我们使用了{{#joinDate}}{{/joinDate}}这对标签来渲染日期。这是POI-tl的语法#和/表示中间是一个可以被渲染的区域POI-tl会根据数据模型中的值类型如java.util.Date自动应用格式化。你也可以使用{{joinDate}}但那样需要你在数据模型中预先格式化成字符串。3.2 第二步准备数据模型Java端在Java代码中我们需要做三件事定义数据对象、组装数据列表、构建POI-tl能识别的数据模型。// 1. 定义员工实体类可使用Lombok简化 Data // Lombok注解生成getter/setter等 public class Employee { private String name; private String workId; private String dept; private Date joinDate; // 构造函数、getter、setter ... } // 2. 在Service或Controller中组装数据和渲染 public void exportEmployeeReport(HttpServletResponse response) throws Exception { // 模拟从数据库查询数据 ListEmployee employeeList new ArrayList(); employeeList.add(new Employee(张三, 1001, 技术部, parseDate(2020-06-01))); employeeList.add(new Employee(李四, 1002, 市场部, parseDate(2019-03-15))); employeeList.add(new Employee(王五, 1003, 技术部, parseDate(2021-08-23))); // ... 可以添加更多 // 3. 构建POI-tl数据模型 MapString, Object dataModel new HashMap(); dataModel.put(employees, employeeList); // 这里的key employees 必须和模板中的 {{#employees}} 对应 // 4. 配置并执行渲染 // 指定模板路径假设模板放在 resources/templates 下 ClassPathResource templateResource new ClassPathResource(templates/employee_template.docx); XWPFTemplate template XWPFTemplate.compile(templateResource.getInputStream()).render(dataModel); // 5. 输出到Http响应流供浏览器下载 response.setContentType(application/vnd.openxmlformats-officedocument.wordprocessingml.document); response.setHeader(Content-Disposition, attachment;filenameemployee_list.docx); template.writeAndClose(response.getOutputStream()); }关键点解析dataModel.put(employees, employeeList)这是连接模板和代码的桥梁。Map的keyemployees必须与模板中的区块标签{{#employees}}的名字完全一致区分大小写。XWPFTemplate.compile(...).render(dataModel)这是核心API。compile方法加载并解析模板文件render方法将数据模型注入模板生成最终文档对象。数据模型中的employeeList里的每个Employee对象在渲染时其属性name,workId等会自动与模板行内的标签{{name}}、{{workId}}等进行匹配并替换。3.3 第三步运行与结果运行上述代码后POI-tl会进行如下操作读取模板发现{{#employees}}标签。获取数据模型中key为employees的值发现它是一个List。对于List中的每一个Employee对象复制一份被{{#employees}}和{{/employees}}包裹的整个表格行。在这个新复制的行里将{{name}}替换为当前员工的name属性值{{workId}}替换为workId以此类推。如果joinDate是Date类型{{#joinDate}}{{/joinDate}}标签会将其渲染为默认的日期格式。将渲染好的所有新行插入到模板中标签所在的位置。最终生成的Word文档将包含一个表格第一行是原始表头后续行是动态生成的员工数据行行数等于employeeList.size()。4. 进阶技巧与深度配置4.1 样式与格式的继承与控制POI-tl最强大的特性之一就是完美的样式继承。模板行里设置的所有格式——字体、大小、颜色、加粗、单元格背景色、边框、合并单元格、行高、列宽——都会在每一行新生成的动态行中保留。但是有时我们需要更精细的控制条件格式化例如对入职超过3年的员工姓名加粗显示。动态计算在表格中增加一列“司龄”根据入职日期计算。这可以通过自定义RenderPolicy渲染策略来实现。POI-tl允许你为特定的标签注册一个自定义的渲染器。// 示例自定义一个渲染策略为特定条件的文本加粗 public class BoldIfSeniorPolicy implements RenderPolicy { Override public void render(ElementTemplate eleTemplate, Object data, XWPFTemplate template) { // eleTemplate是模板标签元素 // data是数据模型中对应此标签的值 // template是当前文档模板 if (data null) return; // 假设传入的数据是Employee对象 Employee emp (Employee) data; // 获取标签所在的Run对象用于设置样式 Run run eleTemplate.getRun(); // 判断是否老员工假设超过3年 long threeYearsAgo System.currentTimeMillis() - (3L * 365 * 24 * 60 * 60 * 1000); if (emp.getJoinDate().getTime() threeYearsAgo) { // 设置加粗 run.setBold(true); // 也可以设置颜色等 // run.setColor(FF0000); } // 最后还是要设置文本内容 run.setText(emp.getName()); // 这里渲染的是姓名 } } // 在配置中使用自定义策略 Configure config Configure.builder() .bind(name, new BoldIfSeniorPolicy()) // 将模板中的{{name}}标签绑定到自定义策略 .build(); XWPFTemplate template XWPFTemplate.compile(templatePath, config).render(dataModel);踩坑记录自定义RenderPolicy功能强大但需谨慎使用。首先它破坏了“模板驱动”的部分纯粹性将样式逻辑又挪回了代码。其次在RenderPolicy中直接操作底层的Run或Paragraph对象需要你对POI的API有一定了解否则容易导致文档损坏。建议仅在标准标签无法满足复杂需求如单元格内嵌图表、复杂条件格式时才使用。4.2 处理复杂嵌套结构业务数据常常是嵌套的。例如一个部门对象包含一个员工列表。POI-tl同样支持嵌套循环。模板设计部门{{deptName}} {{#deptEmployees}} | {{name}} | {{workId}} | {{#joinDate}}{{/joinDate}} | {{/deptEmployees}}在数据模型中你需要提供一个ListDepartment其中每个Department对象有一个deptName属性和一个ListEmployee deptEmployees属性。POI-tl会先遍历部门列表在每个部门区块内再遍历该部门的员工列表。4.3 图片、列表与超链接的嵌入POI-tl不仅支持文本和表格还支持丰富的元素。图片使用{{picture}}标签。数据模型中需要提供一个PictureRenderData对象其中包含图片流、图片类型和尺寸。dataModel.put(logo, new PictureRenderData(120, 120, .png, imageStream));列表使用{{*list}}标签。数据模型中需要提供ListRenderData对象它可以包含多个TextRenderData来定义列表项的样式。超链接使用{{link}}标签。数据模型中需要提供HyperlinkTextRenderData对象包含链接地址和显示文本。这些高级元素的使用让生成的文档不再是单调的表格和文字可以做出非常专业的报告。5. 常见问题排查与性能优化在实际项目中你肯定会遇到各种问题。下面是一个快速排查指南问题现象可能原因解决方案生成的文档中标签{{xxx}}原样显示未被替换。1. 数据模型中的key与模板标签名不匹配。2. 数据模型中该key的值为null。1. 仔细检查拼写和大小写。2. 确保数据模型已正确放入该key-value对。动态表格只生成了一行或行数不对。1.{{#list}}和{{/list}}标签没有完整包裹表格行。2. 传入的数据不是List类型或者是空列表。1. 用Word“显示编辑标记”功能检查标签位置确保它们包裹了整个w:tr。2. 检查Java代码中组装List的逻辑。文档打开报错“文件损坏”。1. 自定义RenderPolicy中错误地操作了文档结构。2. 模板文件本身格式异常如从网页复制粘贴的表格。1. 检查自定义渲染策略的逻辑避免删除或移动关键XML节点。2. 尝试在Word中新建一个简单表格重新制作模板。生成大量数据时内存溢出OOM。一次性渲染的数据行数过多如数万行所有行都保存在内存中的XWPFDocument对象里。1.分页导出业务上支持分页查询和导出。2.流式处理对于极端情况考虑回归低层POI的SXSSFWorkbookExcel或寻找其他流式Word生成方案POI-tl本身不是为流式设计的。日期、数字格式不符合要求。POI-tl的默认格式化可能不满足需求。1. 在数据模型中预先将Date/Number格式化成String再传入。2. 使用{{#joinDate}}{{/joinDate}}配合自定义的RenderPolicy来精细控制格式。单元格合并在动态行中失效。模板行中存在合并单元格但循环复制时合并的属性可能无法正确应用到新行。这是一个已知的复杂情况。解决方案通常更复杂要么避免在循环行中使用合并要么通过自定义RenderPolicy在渲染每行后以编程方式动态设置单元格的合并属性。性能优化建议模板最小化模板文件不宜过大、过于复杂。复杂的样式和大量无关内容会增加解析开销。数据分批对于导出功能务必在业务层实现分页查询。不要试图一次性导出10万条数据到单个Word文档用户体验和系统性能都会很差。通常1000行以内的表格体验是可接受的。缓存Configure对象Configure对象包含了标签绑定、插件等配置。如果配置不变应该将其声明为单例或静态变量避免每次导出都重新创建。复用XWPFTemplate对象不不要这么做。XWPFTemplate对象在write或writeAndClose方法调用后内部状态可能已改变不适合复用。每次导出都应该是compile - render - write - close的完整生命周期。最后再分享一个调试小技巧当你对模板标签的位置不确定时可以将.docx模板文件的后缀改为.zip解压后查看word/document.xml文件。在这个XML文件中搜索你的标签名可以最准确地看到它们所在的XML节点结构这对于解决复杂的渲染问题非常有帮助。不过直接修改这个XML风险很高建议仅作为调试参考修改还是回到Word界面进行。