PyCUPS自定义页边距设置方法

本文介绍如何通过 PyCUPS 的 `PageRegion`、`ImageableArea` 和 PPD 驱动级选项（如 `cupsManualFeed`、`cupsImageableArea`）在自定义页面尺寸中设置上下左右边距，避免内容被裁切，并提供可直接运行的完整示例代码。

在使用 PyCUPS 进行自定义尺寸打印时，仅设置 PageSize（如 "720x432"）并不足以控制内容实际可打印区域——真正决定“内容从哪里开始印、留多少白边”的是 ImageableArea（可打印区域）和 PageRegion（物理页面区域）。CUPS 通过 PPD（PostScript Printer Description）文件定义这些参数，而 PyCUPS 允许我们通过标准打印选项（printFile() 的 options 字典）传入符合 PPD 规范的键值对。

✅ 正确设置边距的核心方法

CUPS 中边距由 ImageableArea 控制，其格式为：
"left bottom right top"（单位：points，1 inch = 72 points），原点位于页面左下角。
例如："72 72 648 360" 表示左/下边距各 1 英寸（72 pt），右/上边距分别留出 9 英寸（648 pt）和 5 英寸（360 pt）——即总宽 10 英寸、高 6 英寸的页面中，内容区域为 648−72 = 576 pt 宽、360−72 = 288 pt 高（即 8×4 英寸）。

同时，必须显式指定 PageRegion 与 PageSize 一致，否则 CUPS 可能忽略 ImageableArea：

import cups

def print_with_margins(
    printer_name: str,
    file_path: str,
    width_in: float = 10.0,     # 页面总宽度（英寸）
    height_in: float = 6.0,      # 页面总高度（英寸）
    left_margin_in: float = 0.5, # 左边距（英寸）
    bottom_margin_in: float = 0.5,  # 下边距（英寸）
    right_margin_in: float = 0.5,   # 右边距（英寸）
    top_margin_in: float = 0.5       # 上边距（英寸）
):
    conn = cups.Connection()

    # 转换为 points（整数更稳定）
    def to_pts(inch): return int(round(inch * 72)

    w_pt, h_pt = to_pts(width_in), to_pts(height_in)
    l_pt, b_pt = to_pts(left_margin_in), to_pts(bottom_margin_in)
    r_pt, t_pt = to_pts(right_margin_in), to_pts(top_margin_in)

    # 构造 PPD 兼容选项
    page_size = f"{w_pt}x{h_pt}"
    page_region = f"{w_pt}x{h_pt}"  # 必须与 PageSize 一致
    imageable_area = f"{l_pt} {b_pt} {w_pt - r_pt} {h_pt - t_pt}"  # 注意：right/top 是“保留宽度”，非坐标

    options = {
        'PageSize': page_size,
        'PageRegion': page_region,
        'ImageableArea': imageable_area,
        'cupsPrintQuality': '3'  # 可选：3=high, 2=medium, 1=draft
    }

    job_id = conn.printFile(printer_name, file_path, "CustomMarginJob", options)
    print(f"✅ 打印任务 {job_id} 已提交，尺寸 {width_in}\"×{height_in}\"，边距 {left_margin_in}\"/{bottom_margin_in}\"/{right_margin_in}\"/{top_margin_in}\"")

# 使用示例（打印一张 10×6 英寸纸，四周留 0.5 英寸边距）
print_with_margins(
    printer_name="TVS_MSP-250CH-TVS-original",
    file_path="/home/tk/Documents/bill.txt",
    width_in=10.0, height_in=6.0,
    left_margin_in=0.5, bottom_margin_in=0.5,
    right_margin_in=0.5, top_margin_in=0.5
)

⚠️ 重要注意事项

• 驱动兼容性优先：并非所有打印机驱动（尤其热敏票据打印机）都完全支持 ImageableArea。若无效，请检查打印机 PPD 文件是否包含 *ImageableArea 条目（可通过 lpoptions -p -l 查看支持选项）。
• 单位严格为 points：ImageableArea 值必须是整数 points，浮点或字符串格式错误将导致静默失败。
• 不要混用 cupsPageSize 或 raw() 调用：问题答案中提到的 printer.raw("PageSize A4: ...") 属于底层 PostScript 指令，不适用于通用 PDF/文本打印，且与 PyCUPS 的 printFile() 接口不兼容，不推荐在常规流程中使用。
• 调试建议：先用 lpoptions -p 查看可用选项；再用 cupsctl --debug-logging 开启 CUPS 日志，观察 ppd 加载和选项解析过程。

✅ 总结

设置自定义页边距 ≠ 仅改 PageSize，而是要协同配置 PageRegion + ImageableArea 两个关键 PPD 选项。掌握这一机制后，即可精准控制票据、标签、信封等特殊介质上的内容定位，大幅提升打印可靠性与专业性。