初步了解XDocReport

XDocReport是一个用来进行文档填充和文档格式转换的java api。在一些项目中，我们可能需要对一份模板里的某些字段进行填充，比如电子合同中需要填写双方信息以及一些金额数据。这时候，我们就可以用XDocReport来实现我们的功能。如果需要把word文档转成pdf，也可以用XDocReport，但是其对中文支持不太好，可能需要用其它工具。所以这篇文章也主要介绍如何使用XDocReport进行文档填充。

文档填充支持的格式包括docx和odt，docx可以使用Office创建和查看，odt可以使用openoffice和libreoffice创建和查看。两种文档在设计模板上会有些许不同，在代码上没有任何区别，下面会详细介绍。

在git上可以找到 XDocReport的源码。在其README.md里有详细的 Getting Started 。通过官方教程，可以非常快速且详细地了解其使用方法。

XDocReport使用的模板引擎是freemarker和velocity,如果想具体什么是模板引擎以及上述两者模板引擎有什么区别，可以找些文章看看。需要提醒的是，官方教程大多数采用的是velocity（当然也有介绍freemarker），但是我这采用的freemarker。二者的填充占位符有所不同，这点需要注意，如果设置反了自然就不会填充成功了。

一个填充的简单例子

这里我们先模拟下需求：完成一份项目文档，需要填充的内容包括项目文档的标题、项目信息、相关人员信息以及一个logo。这里涉及的填充包括字符串填充，pojo填充，list填充以及图片填充，基本可以满足99%的实际需求。接下去，我们需要设计模板，然后再根据模板设计代码，最后进行测试。

设计填充模板

最终效果图

我先展示模板的最终图（freemarker的占位符）：

填充字段设置

首先是字段占位符的设置。我们的文档是docx格式，用office打开后，在你需要填充的地方，先按ctrl+f9，是不是出现了一对有阴影的括弧？如果没出现，可能是因为开启了笔记本上F1-F12的快捷键。在括弧上右键，选择“编辑域”，然后选择“MergeField”(如果是中文的就找找看意思相近的，貌似是邮件合并)。接着在上面填写占位符，如果到时候在程序上选择freemarker模板引擎，那么占位符就是 $,然后后面填写占位的字符串。由于我打算用freemarker，所以可以从图片里看到，我的都是${\dots}。总结一下就是，ctrl+f9 -> 邮件编辑域 -> MergeField -> 填写占位符。$

如果填充的文档是odt格式,那么只需要填写占位符就好了。

	<dependencies>
        <!--xdocreport必备的依赖-->
        <dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocreport.document</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocreport.core</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocreport.template</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocreport.converter</artifactId>
            <version>2.0.1</version>
        </dependency>
        <!--模板引擎相关-->
        <dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocreport.template.freemarker</artifactId>
            <version>2.0.1</version>
        </dependency>
        <!--文档格式相关-->
        <dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocreport.document.docx</artifactId>
            <version>2.0.1</version>
        </dependency>
    </dependencies>
如果采用velocity引擎，或者文档格式为odt，那么就需要换成相应的依赖。 
Project类 
	public class Project {
	    private String name;
	    private String info;
	    省略set、get和全参构造器
Employee类 
	public class Employee {
	    private String name;
	    private String job;
	    private String result;
	    //省略set、get和全参构造器
		//1.通过freemarker模板引擎加载文档，并缓存到registry中
        InputStream in = new FileInputStream(
							"E:\\project\\xdocreport\\file\\test.docx");
        IXDocReport report = XDocReportRegistry
                .getRegistry()
                .loadReport(in, TemplateEngineKind.Freemarker);
这里指定了模板路径以及模板引擎。 
		//2.设置填充字段、填充类以及是否为list。
        FieldsMetadata fieldsMetadata = report.createFieldsMetadata();
        fieldsMetadata.load("project", Project.class);
        fieldsMetadata.load("employees", Employee.class, true);
        fieldsMetadata.addFieldAsImage("logo");
        report.setFieldsMetadata(fieldsMetadata);
结合之前写的模板里的填充字段，也就是域，可以发现 
title只是一个字符串，并不需要设置；
project和employees的区别在于project是单个对象，而employees是多个对象的集合。所以这里employees要加个"true"，表明它是个List。
图片设置和字段设置有所区别
这里设置的域的名字要和模板里的名字保持一致 
模拟填充数据
 
		//3.模拟填充数据
		String title = "项目开发报告";
        Project project = new Project("网站开发", "截至2018年年底");
        List<Employee> employees = new ArrayList<Employee>();
        employees.add(new Employee("张三", "产品", "任务完成"));
        employees.add(new Employee("李四", "开发", "任务完成"));
        IImageProvider logo = new FileImageProvider(
                                new File("E:\\project\\xdocreport\\file\\1.jpg"),
                                        true);
        logo.setSize(200f, 100f);
		//4.匹配填充字段和填充数据，进行填充
        IContext context = report.createContext();
        context.put("title", title);
        context.put("project", project);
        context.put("employees", employees);
        context.put("logo", logo);
        OutputStream out = new FileOutputStream(
                            new File("E:\\project\\xdocreport\\file\\test-out.docx"));
        report.process(context, out);
更多内容…
 
Getting Started的内容非常详细，还有能多内容没来得及看。 
第一次更新：2018.12.2
                    XDocReport介绍初步了解XDocReport适用范围源码地址模板引擎一个填充的简单例子需求设计设计填充模板最终效果图填充字段设置我对填充字段的理解图片填充设置代码编写maven依赖填充类模板加载设置域模拟填充数据开始填充测试结果更多内容...初步了解XDocReport适用范围XDocReport是一个用来进行文档填充和文档格式转换的java api。在一些项目中，我们可能需要对一份...
				如果你要先问我为什么要导出word？那么请你走开，你个杠精！
在完成这个功能时花费了大量的时间查阅资料，发现能满足导出复杂word文档的工具只有xdocreport，如果有其他的工具欢迎分享。废话不多说，上菜！
一、导入包
<dependency>
            <groupId>fr.opensagres.xdocreport</groupId>
            <artifactId>fr.opensagres.xdocrep.
				(一）xdocreport能做什么？
  1.xdocreport是一个java api，它能够根据ms office(docx或者ppt)以及open office的odt创建的xml文档模板，与java模型一起配合生成你想要的docx或者odt文档报告。
  2.同时你可以把生成的docx或者odt文档转换你想要的其它格式，例如pdf，xhtml等。
    所以我们可...
				java freemarker + word 模板 生成 word 文档 （变量替换，数据的循环，表格数据的循环，以及图片的替换）
1，最近有个需求，动态生成 Word 文当并供前端下载，网上找了一下，发现基本都是用 word 生成 xml 然后用模板替换变量的方式
1.1，这种方式虽然可行，但是生成的 xml 是在是太乱了，整理就得整理半天，而且一旦要修改模板，那简直就是灾难，而且据说还不兼容 WPS
1.2，所以笔者找到了以下可以直接用 word 文档作为模板的方法，这里做以下笔记，以下代码依赖于
				XDocReport
 XDocReport表示XML文档报告。 它是Java API，用于将使用MS Office（docx）或OpenOffice（odt），LibreOffice（odt）创建的XML文档与Java模型进行合并，以生成报告并将报告转换为其他格式（PDF，XHTML ...）。
样品和演示
您可以测试我们的在线演示：
 使用XDocReport生成报告的Web应用程序。
 使用REST服务生成报告的Web应用程序。
 一个使用REST服务将docx，odt转换为pdf，xhtml的Web应用程序。
 您可以在找到这些演示的源代码
XDocReport代码是MIT许可下的许可证，但是样本是通过LGPL许可下的许可证，这就是为什么。
XDocReport核心
因为我们喜欢共享我们的代码，所以我们希望使用非常弱的许可证。 这就是为什么我们选择MIT许可作为我们
 xdocreport能解析word转html,但解析出来的是基于word的整套html,往往我们的需求是
按照段落顺序分块解析成一小块的html，并保存数据库，方便我们解决业务上的各种需求。
解决方案：
 修改xdocreport源码，按照段落解析并返回每个段落的html
不知道段落是具体哪一个标题，没有层级概念，无法识别字体，加粗，字体颜色
解决方案：
解析每一个段落的层级标题，字体的属性并返回
不支持解析公式(office公式，wps公式)
解决方案：
 修改xdocreport解析段落源码，支持解析office公式并转mathml格式返回给前端页面显示，wps公式其实就是wmf图片，但是手动插入的公式解析不了，复制的wmf图片却可以解析，xdocreport底层不支持，修改源码让其支持。
备注：当前版本解决了docx转html,doc和docx是两套API，后续更新doc转html.
有任何不懂或者疑问，欢迎评论区留言沟通。
                    程序员小琳: 
                    FieldsMetadata metadata2 = report.createFieldsMetadata();
            metadata2.addFieldAsImage("chart2");
            String picPath = JfreeUtil.chart2(kgceYoyValue, kgceReality, kgceYoyRatio, kgceEffeciency, kgcePlan);
            IImageProvider picture2 = new FileImageProvider(new File(picPath), true);
            // 设置图片大小
            picture2.setSize(175F, 175F);
            report.setFieldsMetadata(metadata2);
            context.put("chart2", picture2);
   FieldsMetadata metadata = report.createFieldsMetadata();
            metadata.addFieldAsImage("chart1");
            String picPath = JfreeUtil.chart1(gson.toJson(xData), gson.toJson(kgceReality), gson.toJson(kgcePlan), gson.toJson(kgceEffeciency), gson.toJson(kgceYoyRatio), gson.toJson(kgceMomRatio));
            IImageProvider picture1 = new FileImageProvider(new File(picPath), true);
            picture1.setSize(415F, 175F);  // 设置图片大小
            report.setFieldsMetadata(metadata);
            context.put("chart1", pi
                XDocReport的简单使用
                    程序员小琳: 
                    怎么在模板里边插入两个图片啊，我这里插入两个图片总是报错
                XDocReport的简单使用
                    _Ricky_: 
                    用了XDocReport后，个人感觉这个缺陷还是很多的，
1、文档不全
2、图片无法实现遍历插入
3、单选复选框无法实现（目前是在模板配置[#if]标签，看起来不友好）
                XDocReport的简单使用
                    山上农夫: 
                    如果是单选按钮和复选按钮，应该怎么实现？
                XDocReport的简单使用
                    Elcker: 
                    必须是 docx