用 brother_ql 写 Python 程序：BrotherQLRaster 类 API 参考与自定义标签编程实战

用 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_ql

brother_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、Windows（USB 和网络两种方式）；
• 支持彩色：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') # 指定打印机型号

所有支持的型号定义在 brother_ql/models.py 的ALL_MODELS列表中，涵盖 QL-500 到 QL-1115NWB，以及 PT-P750W、PT-P900W。

常用方法一览

另外还有两个实用属性：

• get_pixel_width()：返回该型号可打印的像素宽度（每行字节数 × 8）。调用add_raster_data()前务必保证图像宽度与之完全一致，否则会抛出BrotherQLRasterError；
• mtype/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), color=0) 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_page=True) # 结束 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', threshold=70, cut=True)

图像到标签的转换逻辑（缩放、二值化、抖动、红层分离）全部封装在 brother_ql/conversion.py 和 brother_ql/image_trafos.py 中。

指令如何到达打印机：三大后端

生成的data字节流需要经传输后端送达打印机，brother_ql/backends/ 提供三种选择：

网络机型推荐直接用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