用 brother_ql 写 Python 程序BrotherQLRaster 类 API 参考与自定义标签编程实战【免费下载链接】brother_qlPython package for the raster language protocol of the Brother QL series label printers (QL-500, QL-550, QL-560, QL-570, QL-700, QL-710W, QL-720NW, QL-800, QL-810W, QL-820NWB, QL-1050, QL-1060N and more).项目地址: https://gitcode.com/gh_mirrors/br/brother_qlbrother_ql 是一个 Python 包用于控制 Brother QL 系列标签打印机如 QL-500、QL-500、QL-710W、QL-820NWB、QL-1060N 等。它完整实现了兄弟 QL 打印机的光栅Raster打印语言让程序员绕过系统打印驱动直接向打印机发送指令文件——这意味着无需任何打印机驱动甚至在没有官方驱动的树莓派上也能精确控制每一个像素。本文将带你完整梳理核心类BrotherQLRaster的 API并动手完成自定义标签编程实战。为什么用 brother_ql 而不是打印驱动很多程序在给标签设置页面尺寸和边距时总会出错而打印条码这类内容对像素精度要求极高。brother_ql 的独特之处在于零驱动依赖不经过操作系统打印系统直接与打印机对话像素级控制每个点都由你的代码决定适合高精度条码、Logo 标签跨平台支持 Linux、macOS、WindowsUSB 和网络两种方式支持彩色QL-800 系列可在 DK-22251 标签上打印黑红双色。快速安装与验证一条命令即可完成 brother_ql 安装pip install --upgrade brother_ql安装后可用命令行工具快速验证环境brother_ql info labels # 查看所有可用标签尺寸 brother_ql discover # 查找已连接的标签打印机如果打印机带有Editor Lite模式打印前需长按按钮关闭该模式指示灯熄灭否则 USB 打印会失败。BrotherQLRaster 类 API 参考BrotherQLRaster是整个包的核心位于 brother_ql/raster.py。它的工作方式很直观每调用一个add_xxx()方法就往成员变量data中追加一段光栅指令字节最终data就是可直接发送给打印机的完整指令文件。构造与基本属性from brother_ql import BrotherQLRaster qlr BrotherQLRaster(QL-710W) # 指定打印机型号属性说明data累积生成的指令字节流最终要发送的就是它model/model_obj当前型号字符串及对应的 Model 对象exception_on_warning设为True时遇到型号不支持的指令直接抛异常而非仅告警two_color_support当前型号是否支持黑红双色打印pquality打印质量True为高质量默认所有支持的型号定义在 brother_ql/models.py 的ALL_MODELS列表中涵盖 QL-500 到 QL-1115NWB以及 PT-P750W、PT-P900W。常用方法一览方法作用add_initialize()初始化打印机ESC 开启新作业add_invalidate()清空打印机指令缓冲区add_switch_mode()切换到光栅动态命令模式add_media_and_quality(rnumber)设置介质类型、宽度、长度与打印质量add_raster_data(image, second_imageNone)添加图像位图数据第二张图用于 QL-800 系列的红色层add_autocut(autocutFalse)控制是否自动裁切标签add_cut_every(n1)每打印 n 张标签后裁切一次add_compression(compressionTrue)启用 PackBits 压缩减小传输体积add_margins(dots0x23)设置打印边距单位点add_status_information()请求打印机状态信息add_print(last_pageTrue)结束打印发送结束符^Z或换页符另外还有两个实用属性get_pixel_width()返回该型号可打印的像素宽度每行字节数 × 8。调用add_raster_data()前务必保证图像宽度与之完全一致否则会抛出BrotherQLRasterErrormtype/mwidth/mlength设置介质类型、宽度和长度配合add_media_and_quality()使用。自定义标签编程实战从零生成一个标签下面用最少的代码演示完整流程——创建一个 62mm 宽、10 像素高的黑白标签并保存为指令文件from PIL import Image from brother_ql import BrotherQLRaster qlr BrotherQLRaster(QL-710W) qlr.exception_on_warning True # 严格模式尽早暴露问题 # 准备图像宽度必须是 get_pixel_width()62mm 约 696 像素 img Image.new(1, (qlr.get_pixel_width(), 10), color0) qlr.add_initialize() # 初始化 qlr.add_invalidate() # 清缓冲 qlr.add_media_and_quality(0x000000D2) qlr.add_compression(True) # 启用压缩 qlr.add_raster_data(img) # 写入位图 qlr.add_print(last_pageTrue) # 结束 open(label.bql, wb).write(qlr.data)保存后的label.bql文件可以直接通过命令行发送打印brother_ql send -m QL-710W -p tcp://192.168.1.21 label.bql 实战技巧如果不想手写每个add_xxx()调用可以改用高层函数create_label()见 brother_ql/brother_ql_create.py它会自动处理模式切换、边距、裁切、旋转、阈值二值化等繁琐细节from brother_ql import create_label create_label(qlr, my_image.png, 62, threshold70, cutTrue)图像到标签的转换逻辑缩放、二值化、抖动、红层分离全部封装在 brother_ql/conversion.py 和 brother_ql/image_trafos.py 中。指令如何到达打印机三大后端生成的data字节流需要经传输后端送达打印机brother_ql/backends/ 提供三种选择后端连接方式适用系统示例标识符networkTCP 9100 端口全平台WiFi/网口机型tcp://192.168.1.21:9100pyusbUSB全平台usb://0x04f9:0x2015/...linux_kernelUSB仅 Linux/dev/usb/lp0网络机型推荐直接用tcp://IP地址连接最省事USB 机型在 Windows 上需先安装 libusb-win32 设备过滤器。型号与标签的对应关系可查 brother_ql/labels.py 中的LabelsManager包括连续式12/29/38/50/54/62/102mm 等和预裁切式如 23x23、62x100、圆形 d24两大类。常见问题速查BrotherQLUnknownModel型号拼写错误可用brother_ql info models查看支持的型号BrotherQLRasterError: Wrong pixel width图像宽度与型号不符用get_pixel_width()校准尺寸BrotherQLUnsupportedCmd指令不受当前型号支持如对 QL-500 启用压缩可参考各型号的compression、cutting等能力标志。所有异常定义集中在 brother_ql/exceptions.py均以BrotherQLError为基类方便统一捕获。总结掌握BrotherQLRaster就掌握了 brother_ql 的全部精髓追加指令 → 读取data→ 选择后端发送。从简单的一行create_label()调用到逐像素定制双色条码标签这个 API 都能满足——这正是它在树莓派、CI 流水线、仓储系统等场景中广受欢迎的原因。【免费下载链接】brother_qlPython package for the raster language protocol of the Brother QL series label printers (QL-500, QL-550, QL-560, QL-570, QL-700, QL-710W, QL-720NW, QL-800, QL-810W, QL-820NWB, QL-1050, QL-1060N and more).项目地址: https://gitcode.com/gh_mirrors/br/brother_ql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考