Android蓝牙热敏打印机图片打印：ZPL指令与Bitmap点阵转换全流程解析

去年接了一个需求，客户要在 Android 平板上选一张图片，通过蓝牙连接热敏打印机，然后用“斑马指令”把图片绘制打印出来。当时听上去就是“连上蓝牙，发一段数据”的事，结果真正调起来才发现，蓝牙链路、热敏打印、ZPL 指令这三件事是三个独立的大坑，任何一个环节理解不到位，打印出来的就是乱码、白纸，或者干脆连接失败。这篇文章我会把这条链路完整拆开，从蓝牙 SPP 连接、ZPL 指令格式，到 Bitmap 转 1 位点阵数据的转换管线，再把可直接用的代码骨架和排障经验一起写出来，给正在做同类需求的朋友一个完整的参考。

1. 先把需求拆开：蓝牙通道、热敏打印、斑马指令是三件独立的事

1.1 为什么“Android + 热敏打印机”的小票场景这么常见

热敏打印机的优势不需要多讲：体积小、成本低、没有耗材中的色带或墨盒，只需要热敏纸。点餐系统、排队叫号、快递面单、现场登记、医疗导诊、移动收银，几乎都能看到 Android 设备通过蓝牙驱动一台小热敏机的组合。

但这个组合之所以经常把开发者坑了，是因为 Android 端和打印机端的链路是“半封闭”的。Android 系统只负责提供蓝牙连接的基础能力，打印机固件只认自己的指令集。两端之间没有像网络 HTTP 那样统一的“请求-响应”语义，很多问题是两端各自为政造成的。

刚开始我以为是图片传输的格式问题，还在想能不能直接发 PNG 或者 JPEG 给打印机。结果打印机根本不认图片文件，只认指令脚本。这个脚本里有明确的“坐标”“宽度”“高度”“点阵数据”概念，而不是一整个文件。所以做这个需求，第一步不是写代码，而是先搞清楚对端打印机到底接收什么。

1.2 斑马指令 ZPL 在这条链路里的位置

斑马指令的正式名称一般写成 ZPL，业内很多人直接叫“斑马指令”。它本质上是一种页面描述语言，像一段打印脚本。打印机固件拿到这段脚本后，会解析里面的字段，把字符、条码、图形、图片转换成热敏头上一行一行的加热点。

典型的 ZPL 脚本会这样组织：

^XA ^FO20,20 ^GFA,<总字节数>,<每行字节数>,0,<十六进制点阵数据> ^FS ^XZ

^XA是开始指令，^XZ是结束指令，^FO是设置图像输出的原点坐标，^FS表示当前字段结束。图像数据放在^GF指令里，这也是“图片绘制打印”最核心的部分。

需要特别强调一点：ZPL 不是所有热敏打印机都认。有些小票机默认走的是 ESC/POS，另外一些是 TSPL，还有厂家自己的私有指令。如果你的项目标题里明确写了“斑马指令”，那么你的打印机必须要支持 ZPL，或者至少能切换到 ZPL 模式。否则后面做的一切转换工作都是白费。

1.3 ESC/POS 与 ZPL 的简单选择

很多第一次接触的人会问：既然很多热敏机支持 ESC/POS，为什么还要用 ZPL？我也做过对比，简单说：

维度	ESC/POS	ZPL
指令风格	短字节控制码	文本脚本，可读性高
图像打印	需要拼图像光栅流，按列/按行组织	通过^GF直接给点阵数据
适用设备	收银小票机、部分便携热敏机	标签机、面单机、部分小票机
排错难度	控制码容易乱，肉眼难查	脚本可直接打印出来看
对开发者友好度	中低	中高

如果打印机同时支持两者，我建议优先用 ZPL。原因是 ZPL 脚本可以用一个文本文件保存，出了问题可以把指令拼接出来看，检查是不是某个参数不对，排错效率明显更高。这也正是标题里强调“斑马指令图片绘制打印”的原因。

2. 蓝牙连接层：为什么我坚持走 SPP 而不是 BLE

2.1 SPP 是大多数热敏打印机的默认通道

Android 蓝牙分为经典蓝牙和低功耗蓝牙（BLE）两条路线。绝大多数已经出货的热敏小票机、便携标签机，自带的是经典蓝牙 SPP 串口协议。SPP 本质上就是一条虚拟串口，Android 端拿到一个BluetoothSocket，像写文件一样把字节流写进去，打印机会从另一端读。

BLE 不是不能用，但坑更多。BLE 的数据传输是“特征值”读写，一次能塞进单个数据包的字节数有限，超过 MTU 还要分包。而且很多廉价打印机虽然带 BLE，却没有完整实现 GATT 的服务发现，你连上后找不到可写的特征，或者找到了写了几包就断开。

所以我的建议很直接：项目优先探测 SPP，只有确认设备只支持 BLE 时再走 GATT。标题里没有写明具体协议，但从实际设备分布来看，SPP 的概率超过九成。

2.2 搜索设备与过滤规则：不要什么设备都列出来

用系统蓝牙搜索时会搜到手机、耳机、音箱、手环，直接全列出来对用户很不友好。我的做法是维护一个设备过滤列表，根据设备名称里的关键字过滤，例如：

• 包含POS、Printer、58mm、80mm、Thermal等名称的设备优先显示；
• 排除前面几个常见 API 级别上搜到的手机、耳机设备；
• 保留没有名称但返回了 SPP UUID 的设备。

代码上可以先注册BroadcastReceiver监听BluetoothDevice.ACTION_FOUND，收到设备后读取名称和BluetoothClass，再做过滤。

需要特别提醒：Android 6.0 到 Android 11，搜索蓝牙需要定位权限ACCESS_FINE_LOCATION，因为系统认为蓝牙扫描可能推断位置。Android 12 开始又增加了BLUETOOTH_SCAN、BLUETOOTH_CONNECT这类运行时权限。这个不配置好，设备列表永远是空的。

2.3 连接背后最容易忽略的 UUID 和线程模型

SPP 连接有一个固定 UUID，绝大多数设备都认：

private static final UUID SPP_UUID = UUID.fromString("00001101-0000-1000-8000-00805F9B34FB");

部分打印机固件兼容性差，标准 SPP UUID 连不上，需要通过BluetoothDevice.fetchUuidsWithSdp()获取设备公开的 UUID 列表，再用列表里的值创建 socket。

另一个大坑是线程。BluetoothSocket.connect()和OutputStream.write()都会阻塞。如果在主线程调用，轻则界面卡死几秒，重则直接ANR。正确做法是用ExecutorService或子线程处理整个连接和发送流程，完成后通过Handler或回调通知 UI。

连接前还要做一件事：BluetoothAdapter.cancelDiscovery()。如果不取消系统搜索，连接速度会非常慢，甚至一直连不上。我曾经在这个地方卡了两三个小时，最后发现只是忘了取消搜索。

3. ZPL 图像指令核心：一张图片在打印机眼里是点阵，不是文件

3.1^GF参数逐一拆解

ZPL 里用于图像绘制的最核心指令是^GF。不同固件对参数个数的接受程度略有差异，我实际项目里验证过最通用的一种写法是：

^GFA,<总字节数>,<每行字节数>,0,<十六进制数据>

四个参数的含义分别是：

• 第一个：图像总共占多少字节，算法是“每行字节数 × 总行数”；
• 第二个：每行多少字节，由图像宽度决定；
• 第三个：0，部分固件要求的数据描述位，不需要就填 0；
• 第四个：ASCII 编码的十六进制点阵数据。

也有打印机只接受三参数，把中间的 0 去掉即可：

^GFA,<总字节数>,<每行字节数>,<十六进制数据>

建议做功能之前，先用一张 16×16 的纯黑测试图，把两种格式都发给打印机，看哪张能正常出图。这个步骤能帮你快速确定固件版本，比反复调试大图高效得多。

3.2 图像数据为什么要求“1 像素 1 bit、按行补齐”

ZPL 的^GF不会帮你解析 PNG，也不会帮你处理图片压缩，它只认二值化后的点阵。每个像素点用 1 个 bit 表示：1 表示加热打印出黑点，0 表示不加热留白。8 个像素按顺序组成一个字节，字节再转换成两位十六进制字符。

如果图片宽度不是 8 的倍数，比如宽度是 380 像素，那么每行实际需要的字节数是(380 + 7) / 8 = 48字节，也就是 384 个 bit。右边多出来的 4 个 bit 填 0，不参与打印，但必须参与字节对齐。不做对齐的话，从第二行开始所有像素都会错位，打印出来就是斜的。

每一行的像素顺序遵循“高位在前”，即第一个像素放在字节的最高位。举例来说，一行 8 个像素从左到右是1 0 1 0 1 0 1 0，对应二进制10101010，十六进制就是AA。理解了这个规则，你就知道十六进制字符串里的每一位都对应物理矩阵里的一个点。

3.3 先打一张测试图校准格式

我第一次调 ZPL 图像时，没有先做小样，直接发了一张 800×600 的大图，结果打印机吐出来一长串乱码，完全不知道是蓝牙问题还是指令问题。后来老老实实先生成一张小测试图：

^XA ^FO10,10 ^GFA,32,2,0,<64 个 FF> ^FS ^XZ

这条指令里的意思是画一个 16 像素宽、16 像素高的全黑方块。如果打印机出来是一个正方形，说明格式正确；如果出来的是斜线、条纹、或者没有图形，就说明参数集或位序不对。测试图过了，再上真正的业务图片，能省掉 80% 的排查时间。

4. 图片转换管线：从 Bitmap 到 ZPL 十六进制流

4.1 缩放、灰度、阈值的取舍

拿到一张 Bitmap 后，第一步不是遍历像素，而是先搞清楚打印机的物理分辨率。常见热敏小票机打印宽度有 58mm 和 80mm 两种，203dpi 是常见分辨率：

• 58mm 纸，可用打印宽度约 48mm，对应约 384 个点；
• 80mm 纸，可用打印宽度约 72mm，对应约 576 个点。

我在代码里默认把目标宽度控制在 384，如果图片宽度小于 384 就不放大，大于 384 就按比例缩小。这样既能保持比例，也不会让一张小图被放大成马赛克。

缩放过后的图片，还要把每个像素从 ARGB 转成灰度。最简单的方式是取 RGB 的加权平均值：

int gray = (r * 299 + g * 587 + b * 114) / 1000;

拿到灰度值后设置一个阈值，比如 128。小于阈值就认为是黑点，大于阈值就认为是白点。这个方式对logo、截图、签名绰绰有余。如果一定要打印照片，建议再做抖动算法，否则照片会丢失大量层次，但热敏纸本身的灰阶效果也有限，不要抱太高期望。

4.2 按字节打包：每 8 个像素拼成一个字节

核心转换逻辑并不复杂，难点在于处理宽度补齐和位序。

private static String toHexPacked(Bitmap bmp, int threshold) { int width = bmp.getWidth(); int height = bmp.getHeight(); int bytesPerRow = (width + 7) / 8; StringBuilder hex = new StringBuilder(); for (int row = 0; row < height; row++) { int currentByte = 0; int bitIndex = 0; for (int col = 0; col < bytesPerRow * 8; col++) { int bit = 0; if (col < width) { int pixel = bmp.getPixel(col, row); int r = Color.red(pixel); int g = Color.green(pixel); int b = Color.blue(pixel); int luminance = (r * 299 + g * 587 + b * 114) / 1000; bit = luminance < threshold ? 1 : 0; } currentByte = (currentByte << 1) | (bit & 0x01); bitIndex++; if (bitIndex == 8) { hex.append(String.format("%02X", currentByte)); currentByte = 0; bitIndex = 0; } } } return hex.toString(); }

这里我把超出真实宽度的补位像素也一起纳入循环，但它们对应的bit永远是 0。这样做的好处是不需要单独处理边界，代码更不容易出错。

很多人在这一步容易搞反“黑点到底是 1 还是 0”。不同打印机可能相反，如果你打印出来发现图形和预期完全反色（黑色部分变白、白色部分变黑），那就把bit = 1和bit = 0对调，或者在得到字节后执行0xFF - currentByte。

4.3 拼 ZPL 指令时的小心机

图像数据拼好后，ZPL 指令的组装方式如下：

private static String buildZpl(Bitmap bmp, int targetWidth, int threshold) { Bitmap scaled = scaleToWidth(bmp, targetWidth); int bytesPerRow = (scaled.getWidth() + 7) / 8; int totalBytes = bytesPerRow * scaled.getHeight(); String hexData = toHexPacked(scaled, threshold); return "^XA^FO0,0^GFA," + totalBytes + "," + bytesPerRow + ",0," + hexData + "^FS^XZ"; }

有一点要注意：^FO0,0会把图片靠在打印区域的最左上角。如果打印机本身有固定的不可打印边距，图片第一列可能被切掉一点。可以在指令里适当给一个偏移，比如^FO10,10，打印内容往右、往下各移 10 个点，预留安全距离。

另外，ZPL 是文本指令，发送时必须用 ASCII 兼容编码。我习惯用ISO-8859-1，不要用 UTF-8，避免某些固件在解析时把多余字节当成指令的一部分。

5. 完整可用的 Android 打印代码骨架

5.1 蓝牙工具类的简化版本

先放一个最基础的蓝牙连接工具类，去掉了业务包装，保留核心连接和发送逻辑：

public class BluetoothPrinter { private static final UUID SPP_UUID = UUID.fromString("00001101-0000-1000-8000-00805F9B34FB"); private BluetoothSocket socket; public BluetoothSocket connect(BluetoothDevice device) throws IOException { BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter(); if (adapter != null && adapter.isDiscovering()) { adapter.cancelDiscovery(); } BluetoothSocket tmp = device.createRfcommSocketToServiceRecord(SPP_UUID); tmp.connect(); this.socket = tmp; return socket; } public void send(byte[] data) throws IOException { if (socket == null || !socket.isConnected()) { throw new IOException("socket not connected"); } OutputStream out = socket.getOutputStream(); out.write(data); out.flush(); } public void close() { if (socket != null) { try { socket.close(); } catch (IOException ignored) { } } } }

这个类的关键点在于connect()前执行了cancelDiscovery()，避免搜索结果干扰后续连接。如果设备需要自定义 UUID，把createRfcommSocketToServiceRecord换成从设备 UUID 列表里遍历创建即可。

5.2 图片转换与 ZPL 指令拼接

再来看图片处理部分。为了控制篇幅，我把核心函数拆成两个入口：一个是按宽度缩放，一个是把 Bitmap 转成 ZPL 字符串。

public class ZplImageBuilder { public static String build(Bitmap src, int targetWidth, int threshold) { Bitmap scaled = scaleToWidth(src, targetWidth); int bytesPerRow = (scaled.getWidth() + 7) / 8; int totalBytes = bytesPerRow * scaled.getHeight(); String hexData = toHexPacked(scaled, threshold); return "^XA^FO10,10^GFA," + totalBytes + "," + bytesPerRow + ",0," + hexData + "^FS^XZ"; } private static Bitmap scaleToWidth(Bitmap src, int targetWidth) { float scale = Math.min(1f, (float) targetWidth / src.getWidth()); int width = Math.round(src.getWidth() * scale); int height = Math.round(src.getHeight() * scale); return Bitmap.createScaledBitmap(src, width, height, true); } private static String toHexPacked(Bitmap bmp, int threshold) { int width = bmp.getWidth(); int height = bmp.getHeight(); int bytesPerRow = (width + 7) / 8; StringBuilder hex = new StringBuilder(); for (int row = 0; row < height; row++) { int currentByte = 0; int bitIndex = 0; for (int col = 0; col < bytesPerRow * 8; col++) { int bit = 0; if (col < width) { int pixel = bmp.getPixel(col, row); int r = Color.red(pixel); int g = Color.green(pixel); int b = Color.blue(pixel); int luminance = (r * 299 + g * 587 + b * 114) / 1000; bit = luminance < threshold ? 1 : 0; } currentByte = (currentByte << 1) | (bit & 0x01); bitIndex++; if (bitIndex == 8) { hex.append(String.format("%02X", currentByte)); currentByte = 0; bitIndex = 0; } } } return hex.toString(); } }

threshold这里我给的是灰度阈值，默认取 128。如果想调大调小，要根据图片的实际明暗情况来。比如深色 logo 用 128 没问题，但浅色图片用 128 可能丢内容，可以降到 100 或 90。

5.3 主流程调用顺序

业务层的调用顺序必须严格按下面几步来：

1. 用户选择一个设备并确认连接；
2. 在子线程里执行connect()；
3. 读取或解码 Bitmap；
4. 调用ZplImageBuilder.build()生成 ZPL 字符串；
5. 把字符串用ISO-8859-1转成字节数组；
6. 调用send()发送；
7. 发送完成后close()。

示例代码：

ExecutorService executor = Executors.newSingleThreadExecutor(); executor.execute(() -> { try { BluetoothPrinter printer = new BluetoothPrinter(); printer.connect(device); Bitmap bitmap = BitmapFactory.decodeFile(imagePath); String zpl = ZplImageBuilder.build(bitmap, 384, 128); byte[] payload = zpl.getBytes("ISO-8859-1"); printer.send(payload); printer.close(); runOnUiThread(() -> Toast.makeText(this, "打印完成", LENGTH_SHORT).show()); } catch (Exception e) { runOnUiThread(() -> Toast.makeText(this, "打印失败: " + e.getMessage(), LENGTH_SHORT).show()); } });

注意，BitmapFactory.decodeFile解码大图时很容易 OOM，最好先读取BitmapFactory.Options的尺寸信息，再做采样率解码。targetWidth设置为 384 时，采样率控制在 2 到 4 就足够了。

6. 上线前后绕不开的排障清单：乱码、空白、黑块、断连

6.1 打印乱码或直接吐一长串字符

乱码是最常见的问题。遇到这种状况，第一步不是查转换代码，而是确认打印机当前是否处于 ZPL 模式。

有些热敏机出厂默认是 ESC/POS 模式，收到^XA开头的文本后完全不解析，直接当作普通文字打出来。解决方法是看打印机说明书，用指令或按键切换模式。最好先用一个最简单文本测试：

^XA^FO10,10^A0,30,30^FDHello^FS^XZ

如果能打出Hello，说明 ZPL 模式正常。如果打出来是^XA^FO...一长串字符，说明设备模式不对，跟你的图片转换代码一点关系都没有。

另外一个乱码诱因是编码问题。发送 ZPL 时一定要用ISO-8859-1，不要用系统默认编码。在中文环境里，系统字符串转字节默认可能是UTF-8，多字节编码会破坏指令结构。

6.2 图片变黑块或整体空白

图片能出图，但整块都是黑的，或者什么都看不见，这多半是二值化阈值或位序的问题。

先确认阈值：如果原图是白底黑字，而打印出来是一整块黑的，很可能灰度值判断反了。打印机的加热点是“1 表示黑”，你是不是把白底当成了 1？解决办法是打印一张半黑半白的测试图，肉眼判断哪个方向需要反转。

再确认字节序：如果你发现图形是左右镜像、斜向错位，优先检查行的补齐逻辑。宽度不是 8 的倍数时，每一行都必须补齐到 8 的整数倍，否则第二行开始就错位。左右镜像则说明每行的位序反了，需要从字节低位开始读，或者把每行的像素从右往左遍历。

6.3 蓝牙连上后写数据就断

连接成功，但一发送大数据就断开，这个问题我在现场遇到过很多次。常见原因有三个：

• 图片太大，ZPL 指令字符串超过打印机缓存，打印机直接放弃；
• 发送速度太快，打印机的蓝牙缓冲区来不及处理；
• 主线程卡顿导致蓝牙链路超时。

解决办法是把大图数据拆包发送。比如每 1024 个字节写入一次，中间短暂停顿几毫秒：

byte[] payload = zpl.getBytes("ISO-8859-1"); int chunkSize = 1024; for (int i = 0; i < payload.length; i += chunkSize) { int end = Math.min(i + chunkSize, payload.length); out.write(payload, i, end - i); out.flush(); Thread.sleep(5); }

这个时间值不固定，要根据打印机实际处理能力调整。有的打印机缓冲大，可以连续写；有的必须加延时。稳妥起见，先用小图跑通，再逐步加大图片尺寸，找到当前设备的临界点。

还有一个容易被忽略的细节：不要把BluetoothSocket.getInputStream()和OutputStream混用。如果打印机不主动回传数据，你开一个线程去循环读流，可能会把链路读挂。大多数场景下我们只写不读，写完直接close()即可。

下面这张表是我整理的快速自查清单，遇到异常时按顺序排查：

现象	优先检查项	常见根因
打出来是文字指令	ZPL 模式	打印机处于 ESC/POS 模式
乱码	编码方式	使用了 UTF-8 而非 ISO-8859-1
空白	阈值和反色	黑白点判断反了或阈值过低
黑块	字节补齐	宽度不是 8 的整数倍未补齐
图形错位	位序	高位低位顺序理解反了
发送中断	数据分包	图片过大或写入过快
连接卡住	搜索未取消	未执行 cancelDiscovery

7. 最后再分享几条实战经验

这个项目做完后，我最大的体会是：蓝牙热敏打印的难点不在蓝牙，而在图片转换和指令格式之间的匹配。蓝牙连接本身有标准套路，只要线程、UUID、权限没问题，基本都能连上。但一张图能不能打得出来，取决于你是否理解打印机的“点阵世界观”。

我自己后来在项目里留了一个隐藏入口：长按某处可以发送一份测试样张，里面包含纯黑块、纯白块、竖线和横线。不管是换打印机型号还是换固件版本，先打样张再调代码。这个方法帮我避开过很多无效调试。

还有一个经验是想清楚场景再优化。如果业务里只是打印 logo、签名或者简单截图，二值化阈值完全够用，不要为了“更清晰”去加复杂抖动算法。热敏纸本身的物理分辨率就那么高，过度处理反而让图形显得脏。真正要打照片的时候，优先考虑压缩图片尺寸到打印分辨率能承受的范围，而不是盲目提高目标宽度。

希望这份从蓝牙连接到 ZPL 图片绘制的完整方案，能让你少走一段弯路。