SpringBoot整合檔案

前文我們介紹了通過Apache POI通過來匯出word的例子；那如果是word模板方式，有沒有開源庫通過模板方式匯出word呢？poi-tl是一個基於Apache POI的Word模板引擎，也是一個免費開源的Java類庫，你可以非常方便的加入到你的專案中，並且擁有著讓人喜悅的特性。本文主要介紹通過SpringBoot整合poi-tl實現模板方式的Word匯出功能。

• SpringBoot整合檔案 - 整合POI-tl之基於模板的Word匯出
  • 知識準備
    • 什麼是poi-tl
    • poi-tl的TDO模式
      • Template：模板
      • Data-model：資料
      • Output：輸出
  • 實現案例
    • Pom依賴
    • 匯出基於template的word
    • 匯出markdown為word
  • 範例原始碼
  • 參考文章
  • 更多內容

知識準備

需要理解檔案上傳和下載的常見場景和技術手段。@pdai

什麼是poi-tl

如下內容來源於，poi-tl官網。

poi-tl（poi template language）是Word模板引擎，使用Word模板和資料建立很棒的Word檔案。

優勢：

它還支援自定義外掛，如下是官網程式碼倉庫支援的特性

poi-tl supports custom functions (plug-ins), functions can be executed anywhere in the Word template, do anything anywhere in the document is the goal of poi-tl.

Feature	Description
✅ Text	Render the tag as text
✅ Picture	Render the tag as a picture
✅ Table	Render the tag as a table
✅ Numbering	Render the tag as a numbering
✅ Chart	Bar chart (3D bar chart), column chart (3D column chart), area chart (3D area chart), line chart (3D line chart), radar chart, pie chart (3D pie Figure) and other chart rendering
✅ If Condition	Hide or display certain document content (including text, paragraphs, pictures, tables, lists, charts, etc.) according to conditions
✅ Foreach Loop	Loop through certain document content (including text, paragraphs, pictures, tables, lists, charts, etc.) according to the collection
✅ Loop table row	Loop to copy a row of the rendered table
✅ Loop table column	Loop copy and render a column of the table
✅ Loop ordered list	Support the loop of ordered list, and support multi-level list at the same time
✅ Highlight code	Word highlighting of code blocks, supporting 26 languages ​​and hundreds of coloring styles
✅ Markdown	Convert Markdown to a word document
✅ Word attachment	Insert attachment in Word
✅ Word Comments	Complete support comment, create comment, modify comment, etc.
✅ Word SDT	Complete support structured document tag
✅ Textbox	Tag support in text box
✅ Picture replacement	Replace the original picture with another picture
✅ bookmarks, anchors, hyperlinks	Support setting bookmarks, anchors and hyperlinks in documents
✅ Expression Language	Fully supports SpringEL expressions and can extend more expressions: OGNL, MVEL...
✅ Style	The template is the style, and the code can also set the style
✅ Template nesting	The template contains sub-templates, and the sub-templates then contain sub-templates
✅ Merge	Word merge Merge, you can also merge in the specified position
✅ custom functions (plug-ins)	Plug-in design, execute function anywhere in the document

poi-tl的TDO模式

TDO模式：Template + data-model = output

以官網的例子為例：

XWPFTemplate template = XWPFTemplate.compile("template.docx").render(
  new HashMap<String, Object>(){{
    put("title", "Hi, poi-tl Word模板引擎");
}});  
template.writeAndClose(new FileOutputStream("output.docx")); 

• compile 編譯模板 - Template
• render 渲染資料 - data-model
• write 輸出到流 - output

Template：模板

模板是Docx格式的Word檔案，你可以使用Microsoft office、WPS Office、Pages等任何你喜歡的軟體制作模板，也可以使用Apache POI程式碼來生成模板。

所有的標籤都是以{{開頭，以}}結尾，標籤可以出現在任何位置，包括頁首，頁尾，表格內部，文字方塊等，表格佈局可以設計出很多優秀專業的檔案，推薦使用表格佈局。

poi-tl模板遵循「所見即所得」的設計，模板和標籤的樣式會被完全保留。

Data-model：資料

資料類似於雜湊或者字典，可以是Map結構（key是標籤名稱）：

Map<String, Object> data = new HashMap<>();
data.put("name", "Sayi");
data.put("start_time", "2019-08-04");

可以是物件（屬性名是標籤名稱）：

public class Data {
  private String name;
  private String startTime;
  private Author author;
}

資料可以是樹結構，每級之間用點來分隔開，比如{ {author.name} }標籤對應的資料是author物件的name屬性值。

Word模板不是由簡單的文字表示，所以在渲染圖片、表格等元素時提供了資料模型，它們都實現了介面RenderData，比如圖片資料模型PictureRenderData包含圖片路徑、寬、高三個屬性。

Output：輸出

以流的方式進行輸出：

template.write(OutputStream stream);

可以寫到任意輸出流中，比如檔案流：

template.write(new FileOutputStream("output.docx"));

比如網路流：

response.setContentType("application/octet-stream");
response.setHeader("Content-disposition","attachment;filename=\""+"out_template.docx"+"\"");

// HttpServletResponse response
OutputStream out = response.getOutputStream();
BufferedOutputStream bos = new BufferedOutputStream(out);
template.write(bos);
bos.flush();
out.flush();
PoitlIOUtils.closeQuietlyMulti(template, bos, out); // 最後不要忘記關閉這些流。

實現案例

這裡展示SpringBoot整合poi-tl基於word模板匯出Word， 以及匯出markdown為word的例子。

Pom依賴

引入poi的依賴包

基礎的包：

<dependency>
    <groupId>com.deepoove</groupId>
    <artifactId>poi-tl</artifactId>
    <version>1.12.0</version>
</dependency>

外掛的包如下，比如highlight,markdown包

<dependency>
    <groupId>com.deepoove</groupId>
    <artifactId>poi-tl-plugin-highlight</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>com.deepoove</groupId>
    <artifactId>poi-tl-plugin-markdown</artifactId>
    <version>1.0.3</version>
</dependency>

匯出基於template的word

controller中的方法

@ApiOperation("Download Word")
@GetMapping("/word/download")
public void download(HttpServletResponse response) {
    try {
        XWPFTemplate document = userService.generateWordXWPFTemplate();
        response.reset();
        response.setContentType("application/octet-stream");
        response.setHeader("Content-disposition",
                "attachment;filename=user_word_" + System.currentTimeMillis() + ".docx");
        OutputStream os = response.getOutputStream();
        document.write(os);
        os.close();
    } catch (Exception e) {
        e.printStackTrace();
    }
}

Service中的實際方法

@Override
public XWPFTemplate generateWordXWPFTemplate() throws IOException {
    Map<String, Object> content = new HashMap<>();
    content.put("title", "Java 全棧知識體系");
    content.put("author", "pdai");
    content.put("site", new HyperlinkTextRenderData("https://pdai.tech", "https://pdai.tech"));

    content.put("poiText", "Apache POI 是建立和維護操作各種符合Office Open XML（OOXML）標準和微軟的OLE 2複合檔案格式（OLE2）的Java API。用它可以使用Java讀取和建立,修改MS Excel檔案.而且,還可以使用Java讀取和建立MS Word和MSPowerPoint檔案。更多請參考[官方檔案](https://poi.apache.org/index.html)");

    content.put("poiText2", "生成xls和xlsx有什麼區別？POI對Excel中的物件的封裝對應關係？");
    content.put("poiList", Numberings.create("excel03只能開啟xls格式，無法直接開啟xlsx格式",
            "xls只有65536行、256列; xlsx可以有1048576行、16384列",
            "xls佔用空間大, xlsx佔用空間小，運算速度也會快一點"));

    RowRenderData headRow = Rows.of("ID", "Name", "Email", "TEL", "Description").textColor("FFFFFF")
            .bgColor("4472C4").center().create();
    TableRenderData table = Tables.create(headRow);
    getUserList()
            .forEach(a -> table.addRow(Rows.create(a.getId() + "", a.getUserName(), a.getEmail(), a.getPhoneNumber() + "", a.getDescription())));
    content.put("poiTable", table);

    Resource resource = new ClassPathResource("pdai-guli.png");
    content.put("poiImage", Pictures.ofStream(new FileInputStream(resource.getFile())).create());

    return XWPFTemplate.compile(new ClassPathResource("poi-tl-template.docx").getFile()).render(content);
}

private List<User> getUserList() {
    List<User> userList = new ArrayList<>();
    for (int i = 0; i < 5; i++) {
        userList.add(User.builder()
                .id(Long.parseLong(i + "")).userName("pdai" + i).email("[email protected]" + i).phoneNumber(121231231231L)
                .description("hello world" + i)
                .build());
    }
    return userList;
}

準備模板

匯出word

匯出markdown為word

controller中的方法

@ApiOperation("Download Word based on markdown")
@GetMapping("/word/downloadMD")
public void downloadMD(HttpServletResponse response) {
    try {
        XWPFTemplate document = userService.generateWordXWPFTemplateMD();
        response.reset();
        response.setContentType("application/octet-stream");
        response.setHeader("Content-disposition",
                "attachment;filename=user_word_" + System.currentTimeMillis() + ".docx");
        OutputStream os = response.getOutputStream();
        document.write(os);
        os.close();
    } catch (Exception e) {
        e.printStackTrace();
    }
}

Service中實現的方法

@Override
public XWPFTemplate generateWordXWPFTemplateMD() throws IOException {
    MarkdownRenderData code = new MarkdownRenderData();

    Resource resource = new ClassPathResource("test.md");
    code.setMarkdown(new String(Files.readAllBytes(resource.getFile().toPath())));
    code.setStyle(MarkdownStyle.newStyle());

    Map<String, Object> data = new HashMap<>();
    data.put("md", code);

    Configure config = Configure.builder().bind("md", new MarkdownRenderPolicy()).build();

    return XWPFTemplate.compile(new ClassPathResource("markdown_template.docx").getFile(), config).render(data);
}

準備模板

匯出word

範例原始碼

https://github.com/realpdai/tech-pdai-spring-demos

參考文章

http://deepoove.com/poi-tl/

更多內容

告別碎片化學習，無套路一站式體系化學習後端開發: Java 全棧知識體系(https://pdai.tech)