Python PDF 导出 - 使用指南

✅ 解决方案说明

已将PDF导出从浏览器端（jsPDF）改为Python直接生成，使用WeasyPrint库，完美解决中文乱码问题。

优势

• ✓ 无乱码：使用思源宋体（SourceHanSerifSC），完美显示所有中文字符
• ✓ 样式保留：100%保留HTML的所有CSS样式
• ✓ 自动优化：自动处理分页、布局、图表转表格
• ✓ 高质量：生成的PDF可直接用于打印和分发

📦 依赖安装

1. 安装系统依赖（已完成）

brew install pango cairo gdk-pixbuf

2. 安装Python库（已完成）

pip3 install weasyprint

🚀 使用方法

方法一：直接使用Python（推荐）

# 设置环境变量
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH

# 运行导出
python3 ReportEngine/scripts/export_to_pdf.py final_reports/ir/report_ir_xxx.json

# 或从项目根目录运行
python3 -m ReportEngine.scripts.export_to_pdf final_reports/ir/report_ir_xxx.json

方法二：使用便捷脚本（如果有的话）

# 基本用法（自动生成同名PDF）
./pdf_export.sh final_reports/ir/report_ir_xxx.json

# 指定输出路径
./pdf_export.sh final_reports/ir/report_ir_xxx.json my_report.pdf

方法三：在代码中使用

from ReportEngine.renderers import PDFRenderer
import json

# 读取报告数据
with open("report_ir.json", "r") as f:
    document_ir = json.load(f)

# 生成PDF
renderer = PDFRenderer()
renderer.render_to_pdf(document_ir, "output.pdf")

📊 测试样例

已生成两个测试PDF：

1. 综合样式测试 (test_comprehensive.pdf)

   • 包含所有样式元素
   • 字体、标点、列表、表格、KPI卡片等

2. 真实报告 (report_土木工程_python.pdf)

   • 使用真实的土木工程报告数据
   • 完整展示实际使用效果

✨ 特性说明

1. 字体支持

• 优先使用：SourceHanSerifSC-Medium.otf（24MB完整版）
• 备选方案：SourceHanSerifSC-Medium-Subset.ttf（3.7MB子集版）
• 覆盖：所有常用汉字、标点符号、数字、英文

2. 样式保留

• 响应式布局 → PDF优化布局
• 交互按钮 → 自动隐藏
• Chart.js图表 → 自动显示fallback表格
• 所有CSS样式完整保留

3. 分页优化

• 标题不孤立（避免标题单独在页末）
• 表格和卡片避免跨页断裂
• 引用块和callout保持完整

🔧 故障排除

问题1：找不到libpango库

症状：

OSError: cannot load library 'libpango-1.0-0'

解决：

# 使用提供的pdf_export.sh脚本（已自动设置环境变量）
./pdf_export.sh <your_file.json>

# 或手动设置环境变量
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH

问题2：字体文件缺失

症状：

FileNotFoundError: 未找到字体文件

解决： 确保以下任一字体文件存在：

• ReportEngine/renderers/assets/fonts/SourceHanSerifSC-Medium.otf
• ReportEngine/renderers/assets/fonts/SourceHanSerifSC-Medium-Subset.ttf

问题3：PDF仍然有乱码

解决：

1. 检查字体文件是否完整（应该是24MB或3.7MB）
2. 使用pdftotext验证：pdftotext output.pdf - | head
3. 如有问题，重新生成字体子集或使用完整版

📝 开发说明

核心文件

• PDFRenderer - PDF渲染器主类
• HTMLRenderer - HTML渲染器（被PDF渲染器使用）
• export_to_pdf.py - 命令行工具
• pdf_export.sh - 便捷启动脚本（如果有的话）

工作流程

Document IR (JSON)
    ↓
HTMLRenderer.render()
    ↓
HTML with embedded font (base64)
    ↓
WeasyPrint
    ↓
PDF (with SourceHanSerif font)

🎯 下一步

如需集成到Web应用：

1. Flask/FastAPI后端 ```python from flask import send_file from ReportEngine.renderers import PDFRenderer

@app.route('/export_pdf') def export_pdf(): renderer = PDFRenderer() pdf_bytes = renderer.render_to_bytes(document_ir) return send_file(io.BytesIO(pdf_bytes), mimetype='application/pdf')

2. **前端按钮**
   ```javascript
   document.getElementById('export-btn').addEventListener('click', () => {
       window.open('/export_pdf', '_blank');
   });

---

生成时间: 2025-11-18 版本: 1.0 状态: ✅ 已测试，无乱码