如何使用 PyCUPS 为自定义页面尺寸设置页边距（Margins）

pycups 本身不直接支持通过 printfile() 的 options 参数设置页边距（如 pageleft, pagetop），但可通过 ppd 文件中的 cupscommands 或 postscript 命令在打印时动态注入页面设备设置（setpagedevice），从而精确控制边距与自定义尺寸。

在 CUPS 打印系统中，页边距（margins）并非独立的打印选项，而是由 页面设备（pagedevice）参数 控制，包括 /MediaPosition、/PageOrigin、/PageSize 和 /Margins 等。PyCUPS 的 printFile() 方法仅接受标准 IPP 属性（如 PageSize, OrientationRequested），而 Margins 不属于标准 IPP 选项 —— 它需通过底层 PostScript 指令或 PPD 中定义的 cupsCommands 实现。

✅ 正确做法：使用 cupsCommands 注入自定义 setpagedevice

CUPS 支持在 PPD 文件中定义 *cupsCommands: ... 条目，或在运行时通过 conn.addPrinter() / conn.setPrinterAttrs() 配置，但更灵活且无需修改 PPD 的方式是：在打印前向打印机发送原始 PostScript 命令（适用于支持 PostScript 的打印机），或利用 CUPS 的 cupsCommand 机制配合 PageSize 扩展语法。

⚠️ 注意：以下方法要求打印机驱动支持 PostScript 或 CUPS Raster，并启用 cupsCommands 解析（默认开启）。

✅ 推荐方案：扩展 PageSize 字符串以包含 Margins

CUPS 的 PageSize 选项支持扩展语法（见 CUPS PPD Spec §cupsPageSizeCategory），允许在 PageSize 值中嵌入 Margins 和 PageOrigin：

import cups

def print_with_margins(printer_name, file_path, width_inch=10, height_inch=6,
                       left_margin_inch=0.5, bottom_margin_inch=0.3,
                       right_margin_inch=0.5, top_margin_inch=0.3):
    conn = cups.Connection()

    # 转换为点（1 inch = 72 points）
    w, h = int(width_inch * 72), int(height_inch * 72)
    l, b = int(left_margin_inch * 72), int(bottom_margin_inch * 72)
    r, t = int(right_margin_inch * 72), int(top_margin_inch * 72)

    # 构造带 margins 的 PageSize 字符串（格式：WxH+L+B+R+T）
    # 注意：CUPS 要求所有 margin 值均存在，顺序为 Left+Bottom+Right+Top
    page_size_with_margins = f"{w}x{h}+{l}+{b}+{r}+{t}"

    options = {
        'PageSize': page_size_with_margins,
        'fitplot': 'true',  # 自动缩放内容适配页面（可选）
    }

    job_id = conn.printFile(printer_name, file_path, "Print Job with Margins", options)
    print(f"✅ Print job {job_id} sent to '{printer_name}' with custom size {width_inch}\"×{height_inch}\" and margins (L:{left_margin_inch}\", B:{bottom_margin_inch}\", R:{right_margin_inch}\", T:{top_margin_inch}\")")
    return job_id

# 示例调用
print_with_margins(
    printer_name="TVS_MSP-250CH-TVS-original",
    file_path="/home/tk/Documents/bill.txt",
    width_inch=10, height_inch=6,
    left_margin_inch=0.25, bottom_margin_inch=0.25,
    right_margin_inch=0.25, top_margin_inch=0.25
)

? 补充说明：PageSize 扩展语法详解

CUPS 支持的 PageSize 值格式如下（官方文档）：

x[++++]

• 所有单位均为 points（点）
• 和 定义内容区域左下角偏移（即实际页边距）
• 和 用于兼容性（部分驱动会校验总尺寸），建议设为对称值
• 若省略 margin 部分，则等效于 0+0+0+0（无额外边距）

✅ 该方法无需修改 PPD，兼容大多数 CUPS 打印机（包括热敏票据打印机如 TVS MSP-250CH），且比原始 PostScript raw() 调用更安全、可移植。

❌ 不推荐的替代方案（已验证无效或受限）

• print_options = {'PageLeft': '36'} → ❌ IPP 不识别此键，会被忽略
• 使用 conn.printFile(..., options={'media': 'Custom.720x432'}) → ❌ media 仅匹配预定义介质名，无法动态传入 margin
• printer.raw("... setpagedevice")（如答案中所示）→ ⚠️ 仅对 PostScript 打印机有效，且需确保文件为 PS 格式；对文本/PDF/Raster 文件易导致解析失败或空白页

? 总结

方法	是否推荐	适用场景	备注
PageSize=WxH+L+B+R+T	✅ 强烈推荐	所有 CUPS 打印机（含热敏、GDI、Raster）	简洁、标准、无需驱动改造
cupsCommands in PPD	⚠️ 中等	需长期固定 margin 的生产环境	需维护 PPD 文件，灵活性低
Raw PostScript setpagedevice	❌ 不推荐	仅限 PostScript 打印机 + PS 源文件	易出错，调试困难

通过正确构造 PageSize 字符串并传入 margin 偏移值，即可在保持代码简洁的同时，精准控制自定义纸张的打印区域边界。