2025年H5项目斑马打印

本文主要介绍H5项目如何从0开始实现斑马打印机打印功能。主要流程为：斑马官网下载BrowserPrint开发包 => 设备安装BrowserPrint APP => 项目引入BrowserPrint.js => 安装ZebraDesigner => 安装打印设备对应驱动 => 设计打印内容 => 修改输出的ZPL指令调整打印内容

一、设备连接打印机

1.1 软件安装

设备【PC或移动端】H5应用与打印机进行连接交互，需要斑马官网提供的BrowsrerPrint APP作为媒介以蓝牙的方式连接打印机，并通过BrowserPrint.js提供的API与打印机进行数据的传输交互。两者包含在斑马官网提供的BrowserPrint开发包中。[本人主页资源栏已提供本文使用的BrowserPrint开发包与Windows版本ZebraBrowserPrit APP供读者下载参考]

注意：打印设备与H5应用也可以通过局域网络进行交互，本文开发项目仅用蓝牙连接，未使用其他方式进行连接，不作赘述。

1.2 访问权限

在实际测试过程中，可先对设备连接打印机进行测试，即测试BrowserPrint APP与打印机的连接。此处注意在测试过程中需打开BrowserPrint APP的通知权限，否则APP在发现打印设备过程中无法通过弹窗提示打开APP的蓝牙权限访问，进而导致无法通过蓝牙发现并连接打印设备。在连接过程中需要打印机与H5应用设备双向确定，测试时会有弹窗提示。

1.3 打印数据传输

H5项目可以向打印机发生文本文件、图片、与ZPL指令字符串的方式对目标数据进行打印，详细实现方式可参照BrowserPrint中提供的API文档。本项目主要为打印物料标签，需要动态改变打印标签的数据内容，采用发送ZPL指令的方式进行打印。此处用发送图片打印作为示例：

// printObj在本文末尾页面逻辑代码块中定义
const testPrintImg = () => {
  printObj.sendImg(`http://192.168.12.198:8088/tywms/src/assets/images/avatar/pallet-task.png`)
}

二、API引入

2.1 BrowserPrint.js引入

官网提供的BrowserPrint开发包包含对应操作系统的BrowserPrint APP、BrowserPrint.JS开发包、API文档与sample案例。在sample案例中js包由标签方式引入，而本文开发项目采用Vue框架，由于js包中并未将API进行导出export故无法在组件中通过import的方式引入。目前通过在index.html中以标签形式对该API进行引入。

注意，BrowserPrint.js通过标签方式引入后，打包不会将public以外目录下的js文件进行打包另存，即BrowserPrint.js存放在public以外的目录，项目在打包后可能出现未找到对应文件的报错。

三、ZPL指令

3.1 介绍

ZPL指令是斑马公司为斑马打印机打印专门设计的一门语言，打印功能实现需要详细了解ZPL指令的格式与作用，通过标签设计软件对打印内容进行设计后修改ZPL指令调整打印效果，此处相关背景介绍不作赘述。

3.2 常用ZPL指令

查ZPL指令说明文档，本文用到的 ZPL指令均在首次出现时进行说明解释。

3.3 ZPL指令说明文档

本文附有中文的ZPL说明文档，供读者免费下载。

四、标签设计

4.1 安装ZebraDesigner

ZebraDesigner官网下载。

4.2 安装打印设备驱动

成功下载安装ZebraDesigner后需要前往Zebra官网下载打印驱动，指定打印机型号安装后重启ZebraDesigner才能针对指定打印机型号对打印内容进行设计。若ZebraDesigner采用与打印设备型号不同的型号对打印内容进行设计可能出现打印效果异常的问题ZebraDesigner才能获取到指定型号打印机设备并针对设备型号进行标签设计【不同型号打印机的最小打印的单位不同，会导致同一标签输出的ZPL指令在不同打印机下的打印效果不同，而指令中通常以点为单位进行定位】。打印机型号与配置可在打印机设备上进行打印，建议确定打印纸张规格再进行设计【设计前需对打印配置进行设置】。

安装打印机型号驱动下载网址： END USER LICENSE AGREEMENT (UNRESTRICTED SOFTWARE) 【备用：打印机软件支持 | Zebra 驱动程序=》特定于产品的驱动程序】

4.3 打印内容设计

通过拖拽的方式设计打印内容即可，此处不做赘述。

打印内容设计结束后需要获取到该打印内容对应的ZPL指令，此时只需在打印选项卡中选择打印至文件。之后通过记事本等文本编辑软件的方式打开该文件即可获取到ZPL指令。

4.4 ZPL指令可视化

ZPL指令可通过以下网址进行可视化预览，但经测试效果不是很好与实际打印效果有差异仅作参考：Labelary Online ZPL Viewer

五、中文字符打印

4.1 相关ZPL指令

FB(Field Block):用来控制文本块

^FB命令允许将文本打印到定义的块类型格式中。此命令将^FD或^SN字符串格式化为使用为文本字符串指定的原点、字体和旋转的文本块。^FB命令还包含自动换行功能。

格式：^FBa,b,c,d,e
1. a = 文本块行宽度（以点为单位）值：0到标签宽度默认值：0 如果值小于字体宽度或未指定，则不打印文本。
2. b = 文本块中的最大行数值：1到9999 默认值：1 超过最大行数的文本将覆盖最后一行。更改字体大小会自动增加或减小块的大小。
3. c = 在行之间添加或删除空间（以点为单位）值：-9999到9999 默认值：0 除非前面有减号，否则数字被视为正数。正值添加空间；负值删除空间。
4. d = 文本对齐方式值： L = 左 C = 中心 R = 右 J = 对齐默认值：L 如果使用J，则最后一行左对齐。
5. e = 第二行和剩余行的悬挂缩进（以点为单位）值：0到9999 默认值：0

4.2 中文字符打印

斑马打印机在对文本域进行打印时需要定位打印起始位置，字体及其字符宽高

4.2.1 乱码

斑马打印机打印中文字符尽管可采用多种字体，但目前只有宋体可供免费使用，其他中文字符打印需要购买版权，本文使用宋体为例。在指定文本字体后还需指定UTF-8的编码格式否则中文字符仍然会出现乱码的情况，此处指定编码格式的指令为 ^CI28。

^XA
^CWZ,E:SIMSUN.TTF
^CI28
^FO20,20^AZN,40,40^FD这是一段需要打印的中文字符^FS
^XZ

此处ZPL指令示例中，^开头的即为ZPL指令标识符， ^XA表示一段ZPL指令的起始， ^XZ表示一段ZPL指令的结束【类似于一段代码块的 "}"】；^CW..表示将某个字符重命名为其他含义，此处的意思是将字符Z的指代字体更改为宋体，SIMSUN为宋体的英文表达，.TTF为字体库文件的后缀；^CI28指定打印机当前编码格式为UTF-8；^FO表示一段内容的起始，后面数字为指令参数，^FO20,20表示当前指令【截止至^FS,^FS表示一段指令的结束类似于Java中的 ; 】打印内容从横纵坐标（20，20）点开始, ^A指令表示打印一段文本内容，Z表示将此段文本的字体设置为Z即宋体，40，40表示将字符宽高设为40【中文字符似乎只能以24的整数倍放大，设置为40只会向下取值，此处未作测试不影响打印效果】；^FD....…^FS表示一段数据内容

4.2.2 中文字符颜色暗淡

宋体字体的特点为横线比竖线细，故导致中文字符横线颜色暗淡打印效果不清晰的问题。此处采用最原始的将原本打印的字符向下移动一个点位重复打印的方式对字体横线部分进行加粗，增强中文字符的打印清晰度。以下代码采用“1次下右移动重复+1次下移动重复”对中文字符进行加粗：

^XA
^CWZ,E:SIMSUN.TTF
^CI28
^FO20,20^AZN,40,40^FD这是一段需要打印的中文字符^FS
^FO21,21^AZN,40,40^FD这是一段需要打印的中文字符^FS
^FO21,22^AZN,40,40^FD这是一段需要打印的中文字符^FS
^XZ

4.3 自动换行

在数据内容需要动态修改打印的情况下，可能出现数据长度不一需要换行的业务场景，此处通过^FB指令进行实现换行。^FB^FB在实现自动换行时建议不要指定对齐方式为居中对齐，否则可能出现打印位置错位的情况。

^XA
^CWZ,E:SIMSUN.TTF
^CI28
^FO20,20^AZN,40,40^FB320,5^FD这是一段需要打印的中文字符自动换行填充自动换行填充自动换行自动换行自动换行自动换行填充自动换行填充自动换行自动换行自动换行^FS
^FO21,21^AZN,40,40^FB320,5^FD这是一段需要打印的中文字符自动换行填充自动换行填充自动换行自动换行自动换行自动换行填充自动换行填充自动换行自动换行自动换行^FS
^FO21,22^AZN,40,40^FB320,5^FD这是一段需要打印的中文字符自动换行填充自动换行填充自动换行自动换行自动换行自动换行填充自动换行填充自动换行自动换行自动换行^FS
^XZ

此处的^FB指令表示一段长度为320点最大行数为5的文本域，一行字符串宽度超过320后会自动换行，默认采用左对齐的方式。

六、含中文字符二维码打印

在ZebraDesigner中插入二维码时，需在二维码的配置选项卡上对编码进行配置并在配置结束后修改二维码的ZPL指令，配置如图：

注意：在打印内容中同时包含中文字符与二维码中包含中文字符时需分别在打印指令前指定不同的编码方式，否则可能出现乱码。

^XA
^CI0^BY,,0
^FO793,849^BQN,2,8
^FDQM,B0200${item.deliveryDocNo}|${item.itemCode}|${item.itemName}^FS
^CI28
^CWZ,E:SINSUM.TTF
^FO20,20^AZN,40,40^FD这是一段需要打印的中文字符^FS
^XZ

^BY,,0指代条码高度参数，^BQ表示二维码,N为方向，2表示二维码采用增强型，8表示二维码的放大系数，^FDQM指令中Q表示纠错等级，M表示采用手动方式输入，B0200表示编码最大200个字节数据，若缺失B0200则扫码结果的中文字符会以空白符的形式出现。

七、页面逻辑

在打印前获取打印设备（getDefaultDevice），通过打印设备Device对象向打印设备发送ZPL指令对数据内容进行打印(device.send)。

const printObj = {
  // 记录选中设备
  selected_device:{},

  // 记录设备列表
  devices:[],
  // 通用错误提示回调函数
  errorCallBack(errorMessage) {
    alert(errorMessage)
  },
  // 通用读取设备响应数据回调函数
  readCallBack(readData) {
    if( readData === undefined || readData === '' || readData === null ) {
      alert('No Response from Device')
    } else {
      alert(readData + '---response from Device')
    }
  },

  // 获取设备
  getDevice() {
    // 首先获取选中设备
    BrowserPrint.getDefaultDevice('printer', (device) => {
      // 成功获取设备后，将其作为选中设备记录并加入设备列表
      this.selected_device = device
      this.devices.push(device)
      alert('获取打印机成功' + device)
      console.log(device);
      // 2.获取本地的其他设备
      BrowserPrint.getLocalDevices((device_list) => {
        device_list.forEach((item) => {
          // 获取的本地设备只有在 之前没有获取到选中设备 或者 非之前获取到的选中设备时才会加入到设备列表避免重复 
          if(!selected_device || item.uid !== selected_device.uid) {
            devices.push(item)
          }
        })
      },() => {
        alert('error getting local devices')
      }, 'printer')
    }, (error) => {
      alert('getDevices Error :' + error + '（测试发现为BrowserPrint服务未启动导致）')
      this.errorCallBack
    })
  },
    // 发送图像文件到打印机
  sendImg(imgUrl) {
    // let url = window.location.href.substring(0, window.location.href.lastIndexOf('/'))
    // url = url + '/' + imgUrl
    this.selected_device.convertAndSendFile(imgUrl, undefined, this.errorCallBack)
  },
  // 向选中设备中发送数据

  writeToSelectedPrinter(data) {
    try{
      this.selected_device.send(data, () => {
        alert('writeToSelectedPrinter Success!!!')
      }, this.errorCallBack)
    }catch(error) {
      alert('write to selected printer error:' + error)
    }
  },
}

// 页面打印逻辑
printObj.getDevice()
printObj.writeToSelectedPrinter('ZPL字符串')