Flutter中使用TSPL指令打印BITMAP图片失败求助

BITMAP指令核心逻辑 #

TSPL的BITMAP指令是给打印机传输原始点阵二进制数据，而非文本格式的十六进制字符串：

• 指令格式里的bitmap data字段要求直接传入二进制字节流，每个字节对应8个像素的点阵信息（mode=0时，1代表黑像素，0代表白像素）。
• 如果你把二进制字节转成十六进制字符串（比如把0xFF变成"FF"），打印机只会将'F'作为ASCII字符解析打印，完全不会识别为点阵数据。
• 参数细节：
  • mode一般设为0（单色位图），大部分移动打印机不支持灰度/彩色模式；
  • width和height是位图的实际像素尺寸，且宽度需是8的倍数（不足时右侧补白像素凑整），否则点阵字节数会和参数不匹配，导致打印错位或失败。

Flutter下正确转换与发送步骤 #

1. 预处理BMP资源为单色点阵 #

本地BMP通常是24/32位彩色，必须先转成1bit深度的单色位图：

• 使用image库处理：读取BMP后转灰度，再二值化（设置亮度阈值区分黑白）。
• 补全宽度到8的倍数，确保每行点阵能被完整打包为字节。

2. 生成点阵二进制字节流 #

按行处理单色像素，每8个像素打包为1个字节（高位对应左侧像素，符合多数TSPL打印机要求）：

• 例如8个像素[黑,白,黑,白,黑,白,黑,白]会被打包为0xAA。
• 最终得到的Uint8List就是直接可用的bitmap data，无需任何字符串转换。

3. 拼接指令并二进制发送 #

• 先构造文本格式的指令头：BITMAP x,y,width,height,0,（替换x/y为打印坐标，width/height为处理后的位图尺寸），转成UTF-8字节数组。
• 将指令头字节和点阵字节流合并为一个Uint8List，再追加PRINT\r\n指令触发打印。
• 通过蓝牙/USB发送时，必须以二进制方式传输这个合并后的字节数组，不能转成字符串发送（避免非ASCII字节丢失）。

代码示例 #

import 'package:image/image.dart' as img;
import 'dart:typed_data';
import 'package:flutter/services.dart';

// 处理Assets中的BMP为TSPL点阵字节流
Future<Uint8List> processAssetBmpToBitmapData(String assetPath) async {
  ByteData data = await rootBundle.load(assetPath);
  Uint8List bmpBytes = data.buffer.asUint8List();
  img.Image? image = img.decodeImage(bmpBytes);
  if (image == null) throw Exception('无法解析BMP资源');

  // 转单色位图（二值化）
  img.Image monoImage = img.grayscale(image);
  for (int y = 0; y < monoImage.height; y++) {
    for (int x = 0; x < monoImage.width; x++) {
      int luminance = img.getLuminance(monoImage.getPixel(x, y));
      // 亮度低于128设为黑（对应点阵1），否则白（对应点阵0）
      monoImage.setPixel(x, y, luminance < 128 ? 0xFF : 0x00);
    }
  }

  // 补全宽度到8的倍数
  int paddedWidth = (monoImage.width + 7) ~/ 8 * 8;
  int byteCount = (paddedWidth ~/ 8) * monoImage.height;
  Uint8List bitmapData = Uint8List(byteCount);

  // 打包像素为字节
  int byteIndex = 0;
  for (int y = 0; y < monoImage.height; y++) {
    int currentByte = 0;
    for (int x = 0; x < paddedWidth; x++) {
      int bitPosition = 7 - (x % 8);
      if (x < monoImage.width) {
        if (monoImage.getPixel(x, y) == 0xFF) {
          currentByte |= (1 << bitPosition);
        }
      }
      // 每8个像素写入一个字节
      if ((x + 1) % 8 == 0) {
        bitmapData[byteIndex++] = currentByte;
        currentByte = 0;
      }
    }
  }

  return bitmapData;
}

// 发送指令到打印机（示例蓝牙发送逻辑）
Future<void> sendBitmapToPrinter(Uint8List bitmapData, int width, int height) async {
  // 假设已获取蓝牙WriteCharacteristic
  // 构造TSPL指令头
  String cmdHeader = 'BITMAP 20,20,$width,$height,0,';
  Uint8List headerBytes = Uint8List.fromList(cmdHeader.codeUnits);
  // 合并指令头、点阵数据、打印触发指令
  Uint8List fullCommand = Uint8List.fromList([
    ...headerBytes,
    ...bitmapData,
    ...'PRINT\r\n'.codeUnits
  ]);
  
  // 发送二进制数据
  // await bluetoothCharacteristic.write(fullCommand);
}

注意事项 #

• 确认打印机的点阵位序：部分打印机可能要求低位对应左侧像素，若打印的图片左右翻转，调整bitPosition为x % 8即可。
• 避免用字符串拼接点阵数据：任何将二进制字节转成十六进制或Base64字符串的操作，都会导致打印机识别为文本而非点阵。
• 测试时可先发送简单的点阵数据（比如全黑的字节0xFF），验证打印机是否能打印出黑色块，再逐步调试完整图片。

内容的提问来源于stack exchange，提问作者Zahid Tekbaş