Python使用Spire.PDF实现PDF转HTML的三种方式及工具类封装

脚本专家

在数字化内容管理和网页发布中，将PDF转换为HTML是一项实用技能。HTML具有更好的可访问性、搜索引擎友好性和响应式布局，可以将静态PDF转化为可在线查看、搜索和分享的网页内容。本文基于Spire.PDF for Python库，介绍三种转换方式（基本转换、配置选项转换、流式输出），并提供完整的工具类封装及参数调优建议。

环境准备

使用pip安装Spire.PDF库：

2. pip install Spire.PDF

复制代码

安装后即可在项目中操作PDF并执行HTML转换。

基本PDF转HTML转换

最简单的转换是直接将PDF保存为HTML，保留文本、图片和基本布局。

2. from spire.pdf.common import *
3. from spire.pdf import *
5. def ConvertPDFToHTML():
6.     inputFile = "/项目进度.pdf"
7.     outputFile = "ToHTML.html"
8.     doc = PdfDocument()
9.     doc.LoadFromFile(inputFile)
10.     doc.SaveToFile(outputFile, FileFormat.HTML)
11.     doc.Close()
12.     print(f"HTML文件已保存至: {outputFile}")
14. if __name__ == "__main__":
15.     ConvertPDFToHTML()

复制代码

核心只有三步：加载PDF、保存为HTML、关闭文档。生成的HTML可直接在浏览器打开。

配置转换选项：控制图片嵌入与布局

当需要更精细的控制（如是否嵌入图片、图片质量、布局方式）时，使用

2. SetPdfToHtmlOptions()

复制代码

方法。

2. from spire.pdf.common import *
3. from spire.pdf import *
5. def ConvertPDFToHTMLWithOptions():
6.     inputFile = "/示范文本.pdf"
7.     outputFile = "Configured.html"
8.     doc = PdfDocument()
9.     doc.LoadFromFile(inputFile)
11.     # 参数：useCssLayout(False=绝对定位), embedImages(True=Base64嵌入), imageQuality(1-100)
12.     doc.ConvertOptions.SetPdfToHtmlOptions(False, True, 1)
13.     doc.SaveToFile(outputFile, FileFormat.HTML)
14.     doc.Close()
15.     print(f"带嵌入图片的HTML: {outputFile}")
17. if __name__ == "__main__":
18.     ConvertPDFToHTMLWithOptions()

复制代码

2. SetPdfToHtmlOptions

复制代码

的三个参数：
- useCssLayout：False使用绝对定位（保持原布局），True使用流式布局（适合响应式设计）。
- embedImages：True将图片编码为Base64嵌入HTML（自包含文件），False则图片单独保存到文件夹。
- imageQuality：1-100，数值越大质量越高但文件越大。

此方式生成的HTML是自包含的，适合独立分发。注意：原文此处命名为“按页面分割输出”，但实际并未分割页面，而是设置转换选项。如果需要按页面分割，需要额外逻辑（如遍历页面逐一保存），本文暂不展开。

流式输出转换结果

如果希望将HTML内容输出到内存或网络流而不是文件，使用

2. SaveToStream()

复制代码

方法。

2. from spire.pdf.common import *
3. from spire.pdf import *
5. def ConvertPDFToHTMLStream():
6.     inputFile = "./Demos/Data/Sample.pdf"
7.     outputFile = "HTMLStream_Output.html"
8.     doc = PdfDocument()
9.     doc.LoadFromFile(inputFile)
10.     fileStream = Stream(outputFile)
11.     doc.SaveToStream(fileStream, FileFormat.HTML)
12.     fileStream.Close()
13.     doc.Close()
14.     print(f"流输出已保存至: {outputFile}")
16. if __name__ == "__main__":
17.     ConvertPDFToHTMLStream()

复制代码

流式输出适合将HTML内容直接存入数据库、发送给上游服务或进行后续内容修改。也可使用

2. io.BytesIO

复制代码

获取字节数组。

封装PDF转HTML工具类

实际项目中可封装一个工具类，包含基本转换、资源分离、内存流输出和批量转换等功能。

2. from spire.pdf.common import *
3. from spire.pdf import *
4. import os
5. import io
7. class PDFToHTMLConverter:
8.     def __init__(self):
9.         pass
11.     def convert_to_html(self, input_file, output_file,
12.                         embed_images=True, image_quality=80,
13.                         use_css_layout=False):
14.         if not os.path.exists(input_file):
15.             print(f"文件不存在: {input_file}")
16.             return False
17.         try:
18.             doc = PdfDocument()
19.             doc.LoadFromFile(input_file)
20.             doc.ConvertOptions.SetPdfToHtmlOptions(
21.                 use_css_layout, embed_images, image_quality)
22.             doc.SaveToFile(output_file, FileFormat.HTML)
23.             doc.Close()
24.             print(f"✓ 转换成功: {os.path.basename(input_file)} -> {os.path.basename(output_file)}")
25.             return True
26.         except Exception as e:
27.             print(f"✗ 转换失败: {os.path.basename(input_file)} - {str(e)}")
28.             return False
30.     def convert_to_html_with_assets(self, input_file, output_folder):
31.         if not os.path.exists(input_file):
32.             print(f"文件不存在: {input_file}")
33.             return False
34.         try:
35.             if not os.path.exists(output_folder):
36.                 os.makedirs(output_folder)
37.             doc = PdfDocument()
38.             doc.LoadFromFile(input_file)
39.             doc.ConvertOptions.SetPdfToHtmlOptions(False, False, 80)
40.             base_name = os.path.splitext(os.path.basename(input_file))[0]
41.             html_file = os.path.join(output_folder, f"{base_name}.html")
42.             doc.SaveToFile(html_file, FileFormat.HTML)
43.             doc.Close()
44.             print(f"✓ 转换成功: {os.path.basename(input_file)} -> {html_file}")
45.             print(f"  图片资源保存在: {output_folder}")
46.             return True
47.         except Exception as e:
48.             print(f"✗ 转换失败: {os.path.basename(input_file)} - {str(e)}")
49.             return False
51.     def convert_to_memory_stream(self, input_file, embed_images=True,
52.                                  image_quality=80, use_css_layout=False):
53.         if not os.path.exists(input_file):
54.             print(f"文件不存在: {input_file}")
55.             return None
56.         try:
57.             doc = PdfDocument()
58.             doc.LoadFromFile(input_file)
59.             doc.ConvertOptions.SetPdfToHtmlOptions(
60.                 use_css_layout, embed_images, image_quality)
61.             memory_stream = io.BytesIO()
62.             stream = Stream(memory_stream)
63.             doc.SaveToStream(stream, FileFormat.HTML)
64.             doc.Close()
65.             html_content = memory_stream.getvalue()
66.             memory_stream.close()
67.             print(f"✓ 转换成功: {os.path.basename(input_file)} -> 内存流")
68.             return html_content
69.         except Exception as e:
70.             print(f"✗ 转换失败: {os.path.basename(input_file)} - {str(e)}")
71.             return None
73.     def batch_convert_folder(self, input_folder, output_folder,
74.                              embed_images=True, image_quality=80):
75.         if not os.path.exists(input_folder):
76.             print(f"输入文件夹不存在: {input_folder}")
77.             return
78.         if not os.path.exists(output_folder):
79.             os.makedirs(output_folder)
80.         pdf_files = [f for f in os.listdir(input_folder) if f.lower().endswith('.pdf')]
81.         if not pdf_files:
82.             print(f"在 {input_folder} 中未找到PDF文件")
83.             return
84.         print(f"找到 {len(pdf_files)} 个PDF文件，开始转换...")
85.         success_count = 0
86.         fail_count = 0
87.         for pdf_file in pdf_files:
88.             input_path = os.path.join(input_folder, pdf_file)
89.             base_name = os.path.splitext(pdf_file)[0]
90.             output_path = os.path.join(output_folder, f"{base_name}.html")
91.             if self.convert_to_html(input_path, output_path,
92.                                     embed_images=embed_images,
93.                                     image_quality=image_quality):
94.                 success_count += 1
95.             else:
96.                 fail_count += 1
97.         print(f"\n转换完成! 成功: {success_count}, 失败: {fail_count}")
98.         print(f"输出目录: {output_folder}")
100.     def get_html_content_stats(self, html_content):
101.         if html_content is None:
102.             return None
103.         content = html_content if isinstance(html_content, str) else html_content.decode('utf-8')
104.         stats = {
105.             'size_bytes': len(content.encode('utf-8')),
106.             'size_kb': len(content.encode('utf-8')) / 1024,
107.             'has_images': '<img' in content.lower(),
108.             'has_tables': '<table' in content.lower(),
109.             'has_links': '<a ' in content.lower() or '<a href=' in content.lower(),
110.         }
111.         return stats

复制代码

使用示例：

2. def main():
3.     converter = PDFToHTMLConverter()
4.     # 基本转换（图片嵌入）
5.     converter.convert_to_html("./Documents/Report.pdf", "./Output/Report.html",
6.                               embed_images=True, image_quality=90)
7.     # 转换并分离图片
8.     converter.convert_to_html_with_assets("./Documents/Presentation.pdf",
9.                                          "./Output/Presentation_HTML")
10.     # 内存流处理
11.     html_content = converter.convert_to_memory_stream("./Documents/Brief.pdf",
12.                                                       embed_images=True)
13.     if html_content:
14.         stats = converter.get_html_content_stats(html_content)
15.         print(f"HTML统计: {stats}")
16.     # 批量转换
17.     converter.batch_convert_folder("./Documents/PDFs", "./Output/HTMLs",
18.                                    embed_images=True, image_quality=85)
20. if __name__ == "__main__":
21.     main()

复制代码

常见应用场景示例

- 在线文档查看器：将用户上传的PDF转换为HTML（内存流），存储到数据库或缓存实现预览。
- 文档归档系统：批量转换法律文档为HTML，高质量归档（image_quality=95）。
- 内容管理系统集成：将PDF文章转换为HTML（不嵌入图片，由CMS管理），提取内容后发布。

转换质量优化建议

图片处理：
- 嵌入 vs 分离：单文件分发用嵌入，网站发布用分离（可利用CDN缓存）。
- 质量平衡：网页浏览70-85，归档90-100。
- 格式优化：可考虑将Base64图片转为WebP（需额外处理）。

布局保持：
- 需要响应式设计：启用CSS流式布局（

2. useCssLayout=True

复制代码

）。
- 需要精确原始布局：使用绝对定位（

2. useCssLayout=False

复制代码

）。
- 字体处理：确保目标设备有对应字体，或在CSS中引用Web字体。

性能优化：
- 批量处理时建议分批进行，避免内存溢出。
- Web应用中用异步任务（如Celery）处理转换请求。
- 对频繁访问的文档缓存HTML结果。

常见问题与解决方案

布局错乱：调整

2. SetPdfToHtmlOptions

复制代码

参数，使用绝对定位（第一个参数设为False）可更好地保持原始布局。

图片显示异常：检查

2. embedImages

复制代码

设置。若分离图片，确保图片文件夹与HTML的相对路径正确。

中文乱码：确保HTML头部包含

2. <meta charset="UTF-8">

复制代码

，否则手动添加。

文件体积过大：降低

2. imageQuality

复制代码

参数，或分离图片资源并使用压缩格式。

总结

通过Spire.PDF for Python，开发者可以灵活运用基础转换、配置选项和流式处理，实现PDF到HTML的高质量转化。结合工具类封装和参数调优，可轻松集成到在线文档查看器、内容管理系统等场景，提升文档的可访问性和传播效率。

热心网友3

感谢楼主的详细分享！这三种转换方式覆盖了从简单到灵活的场景，工具类封装也很实用，尤其是参数调优的建议对实际项目很有帮助。想请教一下，`useCssLayout=True` 时生成的流式布局在响应式页面中表现如何？另外，工具类里的 `image_quality` 参数默认80，对于高精度图文混排的PDF，是否推荐适当提高数值？期待楼主能补充一下批量转换的完整示例，方便直接复用。再次感谢！

热心网友7

感谢分享！这个工具类封装得很实用，尤其是流式输出和配置选项，正好解决了我之前想把PDF转成内嵌图片的HTML用于邮件展示的需求。问一下，对于带有复杂表格或特殊字体的PDF，Spire.PDF转换后的HTML兼容性怎么样？另外，图片质量设成1和100在实际文件大小上差别大吗？