使用 Python 将 PDF 转换为 HTML

在数字化内容管理和网页发布领域，将 PDF 文档转换为 HTML 格式是一项非常有价值的技能。HTML 作为 Web 的标准格式，具有更好的可访问性、搜索引擎友好性和响应式布局能力。通过转换，你可以将原本静态的 PDF 内容转化为可以在浏览器中轻松查看、搜索和分享的网页内容，大大提升内容的传播效率和用户体验。

本文将详细介绍如何使用 Spire.PDF for Python 库将 PDF 文档转换为 HTML 格式。我们将涵盖基本转换、分页输出、流式处理等多种转换方式，以及实际应用场景中的最佳实践，帮助你构建完整的 PDF 到 HTML 转换解决方案。

环境准备

在开始之前，你需要安装 Spire.PDF for Python 库。可以使用 pip 命令进行安装：

pip install Spire.PDF

安装完成后，你就可以在 Python 项目中使用该库来操作 PDF 文档并执行 HTML 转换操作了。

PDF 转 HTML 的应用场景

在实际工作中，PDF 转 HTML 有多种典型应用场景：

• 网页发布：将 PDF 报告、白皮书转换为网页形式发布到网站
• 在线文档查看：提供基于浏览器的文档预览功能，无需下载 PDF 阅读器
• 搜索引擎优化：HTML 格式更容易被搜索引擎索引，提高内容可见性
• 移动端适配：HTML 可以更好地适应不同屏幕尺寸，提供更好的移动阅读体验
• 内容提取：从 PDF 中提取文本和图像用于其他用途
• 无障碍访问：HTML 格式更容易与屏幕阅读器等辅助技术配合使用

Spire.PDF for Python 提供了简洁的 API 来实现这些转换需求，让你能够灵活控制转换过程和输出格式。

基本的 PDF 转 HTML 转换

最简单的转换方式是直接将 PDF 文件保存为 HTML 格式。以下示例展示了如何完成这一基本任务：

from spire.pdf.common import *
from spire.pdf import *

def ConvertPDFToHTML():
"""将 PDF 文档转换为 HTML 文件"""
inputFile = "/项目进度.pdf"
outputFile = "ToHTML.html"

# 加载 PDF 文档
doc = PdfDocument()
doc.LoadFromFile(inputFile)

# 保存为 HTML 格式
doc.SaveToFile(outputFile, FileFormat.HTML)
doc.Close()

print(f"HTML 文件已保存至: {outputFile}")

if __name__ == "__main__":
ConvertPDFToHTML()

在这个示例中，我们使用了 SaveToFile() 方法并指定 FileFormat.HTML 来完成转换。这种方法非常简单直接，只需三行核心代码即可完成转换。

转换后的 HTML 文件会保留原始 PDF 的文本内容、图片、基本格式和布局。生成的 HTML 可以直接在浏览器中打开查看，也可以嵌入到网页中使用。

按页面分割输出 HTML 文件

当 PDF 文档包含多个页面时，你可能希望将每个页面转换为独立的 HTML 文件，或者将图片嵌入到 HTML 中以便于管理。以下示例展示了如何设置转换选项以实现更精细的控制：

from spire.pdf.common import *
from spire.pdf import *

def ConvertPDFToHTMLWithPages():
"""将 PDF 转换为 HTML，并按页面分割输出"""
inputFile = "/示范文本.pdf"
outputFile = "SplitByPages.html"

# 加载 PDF 文档
doc = PdfDocument()
doc.LoadFromFile(inputFile)

# 设置转换选项
# 参数说明：
# 第一个参数：是否使用 CSS 定位（False 表示使用绝对定位）
# 第二个参数：是否将图片嵌入 HTML（True 表示嵌入为 Base64）
# 第三个参数：图片质量（1 表示最高质量）
doc.ConvertOptions.SetPdfToHtmlOptions(False, True, 1)

# 转换为 HTML 文件
doc.SaveToFile(outputFile, FileFormat.HTML)
doc.Close()

print(f"带嵌入图片的 HTML 文件已保存至: {outputFile}")

if __name__ == "__main__":
ConvertPDFToHTMLWithPages()

这个示例的关键在于使用 SetPdfToHtmlOptions() 方法来配置转换选项。三个参数的含义如下：

这种方法特别适合用于需要将 HTML 文件单独分发的场景，因为所有资源都包含在一个文件中。

使用流式输出转换结果

在某些情况下，你可能不希望直接将转换结果保存到文件，而是希望获取 HTML 内容进行进一步处理，例如存储到数据库、发送到网络或进行内容修改。以下示例展示了如何使用流式输出：

from spire.pdf.common import *
from spire.pdf import *

def ConvertPDFToHTMLStream():
"""将 PDF 转换为 HTML 并输出到流"""
inputFile = "./Demos/Data/Sample.pdf"
outputFile = "HTMLStream_Output.html"

# 加载 PDF 文档
doc = PdfDocument()
doc.LoadFromFile(inputFile)

# 创建文件流
fileStream = Stream(outputFile)

# 将 HTML 内容保存到流
doc.SaveToStream(fileStream, FileFormat.HTML)

# 关闭流
fileStream.Close()
doc.Close()

print(f"HTML 流输出已保存至: {outputFile}")

if __name__ == "__main__":
ConvertPDFToHTMLStream()

这个示例展示了如何使用 SaveToStream() 方法将 HTML 内容输出到流中。流式输出的优势在于：

• 灵活性：可以将内容输出到任何支持流的目的地，如内存、网络套接字或数据库
• 性能：对于大型文档，流式处理可以减少内存占用
• 集成性：更容易与其他系统或服务集成

在实际应用中，你可以将流对象替换为 MemoryStream 来获取 HTML 内容的字节数组，然后进行进一步处理。

实用技巧与高级应用

封装 PDF 转 HTML 工具类

在实际项目中，你可能需要灵活地进行 PDF 到 HTML 的转换。以下是一个实用的工具类，展示了如何封装这些功能：

from spire.pdf.common import *
from spire.pdf import *
import os
import io

class PDFToHTMLConverter:
"""PDF 转 HTML 转换器"""

def __init__(self):
"""初始化"""
pass

def convert_to_html(self, input_file, output_file,
embed_images=True, image_quality=80,
use_css_layout=False):
"""将 PDF 转换为单个 HTML 文件"""
if not os.path.exists(input_file):
print(f"文件不存在: {input_file}")
return False

try:
doc = PdfDocument()
doc.LoadFromFile(input_file)

# 设置转换选项
doc.ConvertOptions.SetPdfToHtmlOptions(
use_css_layout, # 是否使用 CSS 布局
embed_images, # 是否嵌入图片
image_quality # 图片质量
)

# 转换为 HTML
doc.SaveToFile(output_file, FileFormat.HTML)
doc.Close()

print(f"✓ 转换成功: {os.path.basename(input_file)} -> {os.path.basename(output_file)}")
return True

except Exception as e:
print(f"✗ 转换失败: {os.path.basename(input_file)} – {str(e)}")
return False

def convert_to_html_with_assets(self, input_file, output_folder):
"""将 PDF 转换为 HTML 及资源文件夹（图片分离）"""
if not os.path.exists(input_file):
print(f"文件不存在: {input_file}")
return False

try:
# 创建输出文件夹
if not os.path.exists(output_folder):
os.makedirs(output_folder)

doc = PdfDocument()
doc.LoadFromFile(input_file)

# 设置不嵌入图片，图片将保存到单独文件夹
doc.ConvertOptions.SetPdfToHtmlOptions(False, False, 80)

# 生成 HTML 文件名
base_name = os.path.splitext(os.path.basename(input_file))[0]
html_file = os.path.join(output_folder, f"{base_name}.html")

doc.SaveToFile(html_file, FileFormat.HTML)
doc.Close()

print(f"✓ 转换成功: {os.path.basename(input_file)} -> {html_file}")
print(f" 图片资源保存在: {output_folder}")
return True

except Exception as e:
print(f"✗ 转换失败: {os.path.basename(input_file)} – {str(e)}")
return False

def convert_to_memory_stream(self, input_file, embed_images=True,
image_quality=80, use_css_layout=False):
"""将 PDF 转换为 HTML 并返回内存流"""
if not os.path.exists(input_file):
print(f"文件不存在: {input_file}")
return None

try:
doc = PdfDocument()
doc.LoadFromFile(input_file)

# 设置转换选项
doc.ConvertOptions.SetPdfToHtmlOptions(
use_css_layout,
embed_images,
image_quality
)

# 创建内存流
memory_stream = io.BytesIO()
stream = Stream(memory_stream)

# 保存到流
doc.SaveToStream(stream, FileFormat.HTML)
doc.Close()

# 获取 HTML 内容
html_content = memory_stream.getvalue()
memory_stream.close()

print(f"✓ 转换成功: {os.path.basename(input_file)} -> 内存流")
return html_content

except Exception as e:
print(f"✗ 转换失败: {os.path.basename(input_file)} – {str(e)}")
return None

def batch_convert_folder(self, input_folder, output_folder,
embed_images=True, image_quality=80):
"""批量转换文件夹中的所有 PDF 文件"""
if not os.path.exists(input_folder):
print(f"输入文件夹不存在: {input_folder}")
return

# 创建输出文件夹
if not os.path.exists(output_folder):
os.makedirs(output_folder)

# 查找所有 PDF 文件
pdf_files = [f for f in os.listdir(input_folder)
if f.lower().endswith('.pdf')]

if not pdf_files:
print(f"在 {input_folder} 中未找到 PDF 文件")
return

print(f"找到 {len(pdf_files)} 个 PDF 文件，开始转换为 HTML…")

success_count = 0
fail_count = 0

for pdf_file in pdf_files:
input_path = os.path.join(input_folder, pdf_file)
base_name = os.path.splitext(pdf_file)[0]
output_path = os.path.join(output_folder, f"{base_name}.html")

if self.convert_to_html(
input_path,
output_path,
embed_images=embed_images,
image_quality=image_quality
):
success_count += 1
else:
fail_count += 1

print(f"\\n转换完成!")
print(f"成功: {success_count} 个文件")
print(f"失败: {fail_count} 个文件")
print(f"输出目录: {output_folder}")

def get_html_content_stats(self, html_content):
"""获取 HTML 内容的统计信息"""
if html_content is None:
return None

stats = {
'size_bytes': len(html_content.encode('utf-8')),
'size_kb': len(html_content.encode('utf-8')) / 1024,
'has_images': '<img' in html_content.lower(),
'has_tables': '<table' in html_content.lower(),
'has_links': '<a ' in html_content.lower() or '<a href=' in html_content.lower(),
}

return stats

def main():
converter = PDFToHTMLConverter()

# 示例 1: 基本转换（图片嵌入）
converter.convert_to_html(
"./Documents/Report.pdf",
"./Output/Report.html",
embed_images=True,
image_quality=90
)

# 示例 2: 转换并分离图片资源
converter.convert_to_html_with_assets(
"./Documents/Presentation.pdf",
"./Output/Presentation_HTML"
)

# 示例 3: 转换为内存流并进行进一步处理
html_content = converter.convert_to_memory_stream(
"./Documents/Brief.pdf",
embed_images=True
)
if html_content:
# 可以在此处对 HTML 内容进行修改或分析
stats = converter.get_html_content_stats(html_content)
print(f"HTML 统计信息: {stats}")

# 示例 4: 批量转换
converter.batch_convert_folder(
"./Documents/PDFs",
"./Output/HTMLs",
embed_images=True,
image_quality=85
)

if __name__ == "__main__":
main()

这个工具类封装了多种 PDF 转 HTML 的功能，包括基本转换、资源分离、流式处理和批量转换。通过实例化这个类，你可以轻松地在项目中复用这些功能。

常见应用场景示例

场景 1：在线文档查看器

def BuildOnlineDocumentViewer():
"""构建在线文档查看器"""
converter = PDFToHTMLConverter()

# 将用户上传的 PDF 转换为 HTML
html_content = converter.convert_to_memory_stream(
"./Uploads/UserDocument.pdf",
embed_images=True,
image_quality=75 # 适当降低质量以加快加载速度
)

if html_content:
# 将 HTML 内容存储到数据库或缓存
# save_to_database(document_id, html_content)
print("文档已转换为 HTML，可以在线查看")

场景 2：文档归档系统

def ArchiveDocumentsAsHTML():
"""将文档归档为 HTML 格式"""
converter = PDFToHTMLConverter()

# 批量转换并保留原始布局
converter.batch_convert_folder(
"./Archive/Legal_Documents",
"./Archive/HTML_Version",
embed_images=True,
image_quality=95 # 高质量归档
)

场景 3：内容管理系统集成

def IntegrateWithCMS():
"""与内容管理系统集成"""
converter = PDFToHTMLConverter()

# 转换 PDF 为 HTML
html_content = converter.convert_to_memory_stream(
"./Content/Article.pdf",
embed_images=False # 图片由 CMS 管理
)

if html_content:
# 提取 HTML 内容并发布到 CMS
# publish_to_cms(title, html_content)
print("文章内容已准备好发布")

转换质量优化建议

图片处理策略

• 嵌入 vs 分离：对于单文件分发，选择嵌入图片；对于网站发布，选择分离图片以便 CDN 缓存
• 质量平衡：根据使用场景调整图片质量，网页浏览可使用 70-85，归档可使用 90-100
• 格式优化：考虑将图片转换为 WebP 等现代格式以减小文件大小

布局保持技巧

• CSS 布局：对于需要响应式设计的场景，启用 CSS 布局
• 绝对定位：对于需要精确保持原始布局的场景，使用绝对定位
• 字体处理：确保 HTML 中使用的字体在目标设备上可用

性能优化建议

• 批量处理：对于大量文件，考虑分批处理以避免内存问题
• 异步处理：在 Web 应用中，使用异步任务处理转换请求
• 缓存机制：对于频繁访问的文档，缓存转换后的 HTML 内容

常见问题与解决方案

问题 1：转换后布局错乱

解决方案：尝试调整 SetPdfToHtmlOptions 的参数，使用绝对定位（第一个参数设为 False）可以更好地保持原始布局。

问题 2：图片显示异常

解决方案：检查是否正确设置了图片嵌入选项。如果选择分离图片，确保图片文件夹与 HTML 文件的相对路径正确。

问题 3：中文或其他特殊字符显示为乱码

解决方案：确保 HTML 文件使用 UTF-8 编码。可以在转换后检查 HTML 头部是否包含 <meta charset="UTF-8"> 标签。

问题 4：转换后文件体积过大

解决方案：降低图片质量参数，或者选择分离图片资源并使用压缩格式。

总结

通过 Spire.PDF for Python，你可以灵活运用基础转换、流式处理及进阶参数配置，精准实现 PDF 到 HTML 的高质量转化。掌握这些技术，不仅能有效解决布局保持与资源管理问题，还能将其集成至在线文档查看器、内容管理系统等实际场景中，从而大幅提升文档的可访问性与传播效率。