Ohhnews

分类导航

$ cd ..
Baeldung原文

使用 Java 将 Word 文档转换为 HTML

#java#apache poi#文档转换#文件处理#html

[LOADING...]

1. 简介

文档转换曾经是一个复杂且小众的需求，但如今它已成为各种工具集、库甚至不同编程语言原生功能中非常普遍的一部分。

在本教程中，我们将学习如何将 Word 文档转换为可在浏览器中呈现的 HTML 页面。具体来说，我们将学习两种使用 Apache POI 以编程方式转换文档的方法。首先，我们将转换现代的 docx 文件。之后，我们将探讨旧版的 doc 格式。通常，这种用例在企业级应用中非常常见。

2. doc 与 docx 的区别

在 2007 年之前，Microsoft Word 使用的是基于二进制表示的旧版 doc 格式。因此，在不同工具之间处理文档时，互操作性和格式保留变得更加困难。

2007 年之后，Word 转向了基于 Office Open XML 的 docx 格式。这种格式结构化、标准化，并且通常更容易以编程方式进行处理。

正因如此，转换 Word 文档需要根据格式采取不同的方法。为此，我们将从 docx 开始，同时也会涵盖用于向后兼容的 doc 格式。

3. Maven 依赖

为了支持这两种格式，我们需要 Apache POI 模块以及 XDocReport 提供的 XHTML 转换器：

$ xml
<dependency>  
    <groupId>org.apache.poi</groupId>  
    <artifactId>poi-ooxml</artifactId>  
    <version>5.5.1</version>  
</dependency>  
<dependency>  
    <groupId>org.apache.poi</groupId>  
    <artifactId>poi-scratchpad</artifactId>  
    <version>5.5.1</version>  
</dependency>  
<dependency>  
    <groupId>fr.opensagres.xdocreport</groupId>  
    <artifactId>fr.opensagres.poi.xwpf.converter.xhtml</artifactId>  
    <version>2.1.0</version>  
</dependency>

转换器还可以配置 ImageManager，以便将嵌入的图像写入二级存储，并从生成的 HTML 中引用它们。

4. 转换 docx 文档

docx 文件本质上是一个包含 XML 部件的 ZIP 归档文件。Apache POI 通过 XWPFDocument API 隐藏了这种复杂性，为我们处理 Word 内容提供了一种更简洁的方式。

4.1. 使用 Apache POI 转换文档

Apache POI 使用 XWPFDocument 类来表示 docx 文件。

首先，让我们从存储中加载文档：

$ java
public XWPFDocument loadDocxFromPath(String path) {  
    try {  
        Path file = Paths.get(path);  
        if (!Files.exists(file)) {  
            throw new FileNotFoundException("File not found: " + path);  
        }  
        XWPFDocument document = new XWPFDocument(Files.newInputStream(file));  
        boolean hasParagraphs = !document.getParagraphs().isEmpty();  
        boolean hasTables = !document.getTables().isEmpty();  
        if (!hasParagraphs && !hasTables) {  
            document.close();  
            throw new IllegalArgumentException("Document is empty: " + path);  
        }  
        return document;  
    } catch (IOException ex) {  
        throw new UncheckedIOException("Cannot load document: " + path, ex);  
    }  
}

在上面的代码中，我们从路径加载 docx 文件并拒绝空文档。

接下来，我们为生成的 HTML 配置 XHTMLOptions。XDocReport 支持 ImageManager，它将提取的图像存储在与最终 HTML 输出所在的目录相同的 images 目录中：

$ java
private XHTMLOptions configureHtmlOptions(Path outputDir) {  
    XHTMLOptions options = XHTMLOptions.create();  
    options.setImageManager(new ImageManager(outputDir.toFile(), "images"));  
    return options;  
}

现在，我们可以转换文档并将 HTML 文件保存到输入文档的同级目录下：

$ java
public void convertDocxToHtml(String docxPath) throws IOException {  
    Path input = Paths.get(docxPath);  
    String htmlFileName = input.getFileName().toString().replaceFirst("\\.[^.]+$", "") + ".html";  
    Path output = input.resolveSibling(htmlFileName);  
    try (XWPFDocument document = loadDocxFromPath(docxPath);
      OutputStream out = Files.newOutputStream(output)) {  
        XHTMLConverter.getInstance().convert(document, out, configureHtmlOptions(output.getParent()));  
    }  
}

接下来，让我们编写一个测试来验证转换：

$ java
@Test  
void givenSimpleDocx_whenConverting_thenHtmlFileIsCreated() throws IOException {  
    DocxToHtml converter = new DocxToHtml();  
    Path docx = Paths.get(this.getClass().getResource("/sample.docx").getPath());  
    converter.convertDocxToHtml(docx.toString());  
    Path html = docx.resolveSibling("sample.html");  
    assertTrue(Files.exists(html));  
    String content = Files.lines(html, StandardCharsets.UTF_8)  
        .collect(Collectors.joining("\n"));  
    assertTrue(content.contains("<html"));  
}

正如我们所见，我们正在以 UTF-8 格式读取文件，Apache 库已正确保存了该格式。但还有其他事项需要考虑。

4.2. 处理大型文档

对于大型文档，资源管理至关重要。使用 try-with-resources 有助于在转换完成后立即释放流和文档数据。

如果需要，可以异步运行转换，以防止大文件阻塞请求线程。

4.3. 处理嵌套表格和复杂格式

最后，我们在此并未考虑嵌套表格和复杂布局。因此，输入的 Word 文档在视觉上可能并不总是与 HTML 完全匹配。该函数最适用于常规段落、表格和基本格式，但它有一定的局限性。例如，示例 docx 文件包含一个在输出文档中未转换的图表。为简单起见，我们在此不进行转换。

尽管如此，在生产系统中，最好添加带有真实示例文档的回归测试，以反映应用程序可能需要支持的布局。

5. 旧版 doc 转换

较旧的 doc 格式由 POI 的 HWPF API 而非 XWPF 处理。Apache POI 为此用例提供了 WordToHtmlConverter：

$ java
public void convertDocToHtml(String docPath) throws Exception {  
    Path input = Paths.get(docPath);  
    String htmlFileName = input.getFileName().toString().replaceFirst("\\.[^.]+$", "") + ".html";  
    Path output = input.resolveSibling(htmlFileName);  
    Path imagesDir = input.resolveSibling("images");  
    Files.createDirectories(imagesDir);
      
    try (InputStream in = Files.newInputStream(Paths.get(docPath));
      OutputStream out = Files.newOutputStream(output)) {  
        HWPFDocumentCore document = WordToHtmlUtils.loadDoc(in);  
        Document htmlDocument = DocumentBuilderFactory.newInstance()  
            .newDocumentBuilder()  
            .newDocument();
              
        WordToHtmlConverter converter = new WordToHtmlConverter(htmlDocument);  
        converter.setPicturesManager((content, pictureType, suggestedName, widthInches, heightInches) -> {  
            Path imageFile = imagesDir.resolve(suggestedName);  
            try {  
                Files.write(imageFile, content);  
            } catch (IOException e) {  
                throw new RuntimeException(e);  
            }  
            return "images/" + suggestedName;  
        });
        
        converter.processDocument(document);  
        
        Transformer transformer = TransformerFactory.newInstance()  
            .newTransformer();  
        transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");  
        transformer.setOutputProperty(OutputKeys.METHOD, "html");  
        transformer.transform(new DOMSource(converter.getDocument()), new StreamResult(out));  
    }  
}

此流程在内部有所不同，但总体思路是一样的：加载 Word 文档、转换它，并将 HTML 写入存储。此外，对于 doc 格式，我们必须明确指定文档的编码。

此外，图像转换部分需要更多的配置。

6. 结论

在本教程中，我们学习了如何使用 Apache POI 将 Word 文档转换为 HTML。

我们介绍了使用 XWPFDocument 和 XHTMLConverter 处理现代 docx 文件，随后研究了使用 WordToHtmlConverter 处理旧版 doc 文件。

一如既往，代码可在 GitHub 上找到。