xlfill2pdf 0.2.1

Excel to PDF converter with font support

xlfill2pdf

🚧 警告：这是一个"能用就行"的项目！

💡 如果发现 bug，那一定是特性！

🔧 代码写得不够优雅？随时欢迎 PR！

🎯 目标是：能用 > 好用 > 很好用

一个用于将 Excel 文件转换为 PDF 的工具，支持占位符替换、二维码生成、水印添加等功能。 本项目是自用代码整理后的开源版本，功能可能不够完善，但核心功能已经可以正常使用。 欢迎根据实际需求修改代码，如果对你有帮助，请点个星！

特性

• 支持变量替换
• 支持多图片自动布局
• 支持二维码生成（普通二维码和带信息二维码）
• 支持水印添加
• 支持自定义字体
• 支持网络图片和本地图片
• 支持网络 Excel 文件

安装

pip install xlfill2pdf

基础使用

from xlfill2pdf import FontManager, ExcelProcessor

# 创建字体管理器
font_manager = FontManager()
font_manager.set_font("/path/to/your/font.ttf")  # 可选：设置自定义字体

# 创建处理器
processor = ExcelProcessor(
    font_manager=font_manager,
    watermark_text="机密",  # 可选：添加水印
    watermark_alpha=0.1,    # 水印透明度
    watermark_angle=-45,    # 水印角度
    watermark_color=(0, 0, 0)  # 水印颜色 (R,G,B)
)

# 处理数据
data = {
    "name": "张三",
    "id": "12345"
}

# 转换为 PDF
pdf_data = processor.process_excel_to_pdf("template.xlsx", data)

# 保存 PDF
with open("output.pdf", "wb") as f:
    f.write(pdf_data)

Excel 模板格式

在 Excel 模板中使用以下格式的占位符：

• 文本占位符：{{name}}
• 二维码占位符：{{id.二维码}}

自定义处理器

可以注册自定义处理器来处理特殊的占位符：

def handle_image(cell, field_name, data_dict):
    img = openpyxl.drawing.image.Image("image.png")
    img.width = 100
    img.height = 100
    cell.value = None
    column_letter = openpyxl.utils.get_column_letter(cell.column)
    anchor = f"{column_letter}{cell.row}"
    img.anchor = anchor
    return img, column_letter, cell.row # 返回图片对象、锚点、行号
    # return 'xxxx' 则替换为 'xxxx'

# 注册处理器
processor.register_handler(".图片", handle_image)

水印设置

processor = ExcelProcessor(
    font_manager=font_manager,
    watermark_text="机密文件",      # 水印文字
    watermark_alpha=0.1,           # 透明度 (0-1)
    watermark_angle=-45,           # 角度
    watermark_color=(216, 0, 54)   # RGB颜色
)

生成增加自定义信息的二维码

QRCodeGenerator 是一个功能强大的二维码生成器类，支持在二维码周围添加自定义文字信息。它提供了灵活的配置选项和多种输出格式。

主要功能

• 生成标准二维码
• 支持自定义背景尺寸和颜色
• 支持在二维码周围添加文字说明
• 支持自定义字体和字体样式
• 提供多种输出格式（bytes、文件路径、临时文件）
• 支持上下文管理器（Context Manager）

初始化参数

• font_manager: FontManager 实例，用于管理字体
• background_size: 背景图尺寸，默认 (350, 180)
• background_color: 背景颜色，默认白色
• qr_size: 二维码尺寸，默认 (100, 100)
• qr_position: 二维码在背景中的位置，默认 (20, 40)
• default_font_size: 默认字体大小，默认 12
• default_font_color: 默认字体颜色，默认黑色
• output_type: 输出类型，可选 "path"、"temp"、"bytes"
• output_path: 输出文件路径（当 output_type 为 "path" 时必需）

核心方法

create_info_qrcode

创建带有文字信息的二维码。

参数：

• qr_data: 二维码数据内容
• text_info: 文字信息配置字典

from xlfill2pdf import QRCodeGenerator, FontManager
初始化
font_manager = FontManager()
generator = QRCodeGenerator(
font_manager=font_manager,
background_size=(400, 200),
qr_size=(120, 120)
)
创建带信息的二维码
text_info = {
"title": {
"text": "产品信息",
"position": (150, 40),
"font_size": 32,
"color": "black"
},
"code": {
"text": "产品编号：A12345",
"position": (150, 80),
"font_size": 12
}
}
result = generator.create_info_qrcode(
qr_data="https://example.com",
text_info=text_info
)

'''
1. 使用 "path" 输出类型时必须提供 output_path
2. 使用 "temp" 输出类型时，文件会在对象销毁时自动清理
3. 建议使用上下文管理器来确保临时文件的正确清理
4. 文字信息字典中的 "text" 和 "position" 是必需的键
5. 确保使用的字体文件存在且可访问
'''

example

API 参考

FontManager

字体管理器，用于管理 PDF 生成时使用的字体。

font_manager = FontManager()
font_manager.set_font("/path/to/font.ttf", "FontName")

ExcelProcessor

Excel 处理器，负责转换和生成 PDF。

ExcelProcessor 参数说明

• font_manager: FontManager 实例，用于管理字体
• prefix: 变量前缀，默认 "{{"
• suffix: 变量后缀，默认 "}}"
• qrcode_suffix: 二维码后缀，默认 ".qrcode"
• image_suffix: 图片后缀，默认 ".png"
• info_qrcode_suffix: 带信息二维码后缀，默认 ".info_qrcode" (新增)
• use_default_image_handlers: 是否使用默认图片处理器，默认 True
• use_default_qrcode_handlers: 是否使用默认二维码处理器，默认 True
• use_default_info_qrcode_handlers: 是否使用默认带信息二维码处理器，默认 True (新增)
• watermark_text: 水印文字，默认 None
• watermark_alpha: 水印透明度，默认 0.1
• watermark_angle: 水印角度，默认 -45
• watermark_color: 水印颜色，默认 (0, 0, 0)
• qrcode_template: 二维码信息模板，默认 None (新增)

qrcode_template = {
    "title": {
        "text": "设备标识牌",
        "position": (150, 40),
        "font_size": 32, # 字体大小 选填
        "color": "black", # 字体颜色 选填
    }
}

注意事项

1. 确保系统中安装了所需的字体, 使用默认的字体可能显示错误（如：你显示为尼等）
2. Excel 模板中的占位符格式必须严格匹配
3. 图片处理需要足够的系统内存
4. 临时文件会自动清理

License

MIT