xhtml2pdf 高级使用指南：从脚本到Django集成-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00890/article/details/148886652

xhtml2pdf 高级使用指南：从脚本到Django集成

前言

xhtml2pdf 是一个强大的Python库，用于将HTML/CSS转换为PDF文档。本文将从技术专家的角度，深入讲解xhtml2pdf的高级使用方法，包括Python脚本集成、Django应用中的使用以及命令行工具操作。

Python脚本中的基础使用

核心功能实现

在Python脚本中使用xhtml2pdf的核心是pisa.CreatePDF函数。这个函数接受HTML内容作为输入，生成PDF文件作为输出。下面是一个完整的示例：

from xhtml2pdf import pisa

# 启用日志记录（调试时很有用）
pisa.showLogging()

# 定义HTML内容
source_html = """
<html>
    <body>
        <p>To PDF or not to PDF</p>
    </body>
</html>
"""

# 创建并写入PDF文件
with open("test.pdf", "w+b") as result_file:
    pisa_status = pisa.CreatePDF(
        source_html,       # 要转换的HTML内容
        dest=result_file   # 接收结果的文件对象
    )

    if pisa_status.err:
        print("转换过程中发生错误！")

内存中操作

有时我们不需要生成物理文件，而是希望在内存中处理PDF内容。这时可以使用io.BytesIO：

from io import BytesIO
from xhtml2pdf import pisa

# 在内存中创建PDF
pdf_buffer = BytesIO()
pisa.CreatePDF("<html><body><h1>内存PDF示例</h1></body></html>", dest=pdf_buffer)

# 获取PDF内容
pdf_content = pdf_buffer.getvalue()

Django应用中的集成

静态资源处理

在Django中使用xhtml2pdf时，最大的挑战是如何正确处理静态资源（CSS、图片等）。我们需要创建一个link_callback函数来处理相对URL到绝对路径的转换：

import os
from django.conf import settings
from django.contrib.staticfiles import finders

def link_callback(uri, rel):
    """
    将HTML中的URI转换为xhtml2pdf可访问的绝对系统路径
    """
    # 尝试通过静态文件查找器定位资源
    result = finders.find(uri)
    
    if result:
        if not isinstance(result, (list, tuple)):
            result = [result]
        path = os.path.realpath(result[0])
    else:
        # 处理媒体文件和静态文件
        if uri.startswith(settings.MEDIA_URL):
            path = os.path.join(settings.MEDIA_ROOT, uri.replace(settings.MEDIA_URL, ""))
        elif uri.startswith(settings.STATIC_URL):
            path = os.path.join(settings.STATIC_ROOT, uri.replace(settings.STATIC_URL, ""))
        else:
            return uri  # 返回原始URI（可能是绝对URL）
    
    # 验证文件是否存在
    if not os.path.isfile(path):
        raise RuntimeError(f'资源URI必须以{settings.STATIC_URL}或{settings.MEDIA_URL}开头')
    
    return path

Django视图实现

在Django视图中使用xhtml2pdf生成PDF响应：

from django.http import HttpResponse
from django.template.loader import get_template

def generate_pdf_view(request):
    # 准备模板上下文
    context = {
        'title': 'PDF报告',
        'content': '这是动态生成的PDF内容',
        'user': request.user
    }
    
    # 加载并渲染模板
    template = get_template('report_template.html')
    html = template.render(context)
    
    # 创建PDF响应
    response = HttpResponse(content_type='application/pdf')
    response['Content-Disposition'] = 'filename="generated_report.pdf"'
    
    # 生成PDF
    pisa_status = pisa.CreatePDF(
        html,
        dest=response,
        link_callback=link_callback  # 使用上面定义的callback
    )
    
    # 错误处理
    if pisa_status.err:
        return HttpResponse('PDF生成失败，请联系管理员')
    
    return response

命令行工具使用

xhtml2pdf提供了便捷的命令行工具，可以直接转换HTML文件为PDF：

基础转换

xhtml2pdf input.html

这会将input.html转换为input.pdf

高级选项

指定输出文件名：

xhtml2pdf input.html -o custom_output.pdf

转换后自动打开PDF：
```
xhtml2pdf -s input.html
```
使用自定义CSS：
```
xhtml2pdf --css style.css input.html
```

设置页面大小（如A4横向）：

xhtml2pdf --page-size A4 --page-orientation landscape input.html

最佳实践与技巧

模板设计：
- 使用专门的PDF模板，而不是复用网页模板
- 保持布局简单，避免复杂CSS
- 使用固定尺寸（如mm、pt）而非相对单位（如em、%）
性能优化：
- 对大文档使用分页（page-break-before/after）
- 缓存频繁使用的PDF
- 考虑使用Celery异步生成PDF
错误处理：
- 始终检查pisa_status.err
- 记录转换日志
- 提供用户友好的错误信息
字体管理：
- 嵌入所需字体
- 使用通用字体作为后备