打印机 SDK - UniApp 官方示例项目说明

本文档基于对 打印机SDK/uniapp 源码的梳理，以及通过 MCP Word 服务 读取的 doc/uniapp使用说明.docx 内容整理。doc/FW20025/uniapp Demo 开发文档.docx 等较大文档需本地打开查看。

---

一、官方使用说明（来自 uniapp使用说明.docx）

以下为通过 MCP 从 doc/uniapp使用说明.docx 提取的正文要点。

项目结构说明

• 佳博打印机 ESC/TSC 打印指令封装组件
  
• uniapp-sdk 使用说明文档
  
• 安卓原生本地插件
  
• demo 演示页面
  

打印指令调用说明

1. 引入组件

var tsc = require('../../components/gprint/tsc.js')
var esc = require('../../components/gprint/esc.js')

2. 创建指令对象

var command = tsc.jpPrinter.createNew()   // 标签
var command = esc.jpPrinter.createNew()    // 票据

3. ESC 指令编程（票据模式）

流程：初始化 → 调用打印对象方法 → 打印输出（可循环）。

command.init()
command.setText(1,1,2,1,0,0,"5大云优势，提供一体式创新解决方案")
command.setBar(1,1,5,80,3, "11111111111")
command.setQR(2,12,"L","https://www.baidu.com/")
command.setPrint()

4. TSC 指令编程（标签模式）

流程：设置全局属性（标签大小、间隙、清空缓存、速度等）→ 设置各对象 → 打印输出。

command.setSize(40, 30)
command.setGap(2)
command.setCls()
command.setText(50, 10, "TSS24.BF2", 1, 1, "打印测试")
command.setQR(50, 50, "L", 5, "A", "www.poscom.cn")
command.setPagePrint()

蓝牙打印

• 流程：开启定位(uni.getLocation) → 打开蓝牙(uni.openBluetoothAdapter) → 获取蓝牙状态 → 搜索设备(uni.startBluetoothDevicesDiscovery) → 连接(uni.createBLEConnection) → 获取服务(uni.getBLEDeviceServices) → 发送数据(uni.writeBLECharacteristicValue)。
• 参考 API：uniapp 官方 定位、蓝牙。
• 注意：
  1. 发送成功但不打印，多为数据格式不符合 ESC/TSC 或编码非 gb18030，需检查格式与编码。
  2. 特征值 write=true 表示可写，多个可写特征任选其一即可发送。
  3. 安卓底层可能限制单包约 20 字节，需按约 20 字节分包多次发送，Demo 中有拆分示例。

Socket 网络打印

• 佳博打印机通过网线/WIFI 联网后，默认监听 9100 端口。
• 在页面输入打印机 IP 和端口（默认 9100）连接，连接成功后即可通信。
• 注意：
  1. 一台打印机同一时间只允许一个客户端连接；未正常断开时需重启打印机才能再连。
  2. 图片打印若未完全实现，可参考 uniapp 安卓原生取图 API，再参考蓝牙页的位图处理。
  3. 默认启动页在 pages.json 的 condition -> path 中修改。

---

二、目录结构

路径	说明
./components/gprint/	打印指令与蓝牙工具：TSC 标签指令、ESC 票据指令、经典/低功耗蓝牙封装
./components/data/	示例数据（如 base64Data.js）
./doc/	开发文档（Word）：使用说明、Demo 开发文档、需求评估、流程图等
./doc/FW20025/	FW20025 相关：uniapp Demo 开发文档、功能框图、流程图、需求评估模板
./nativeplugins/moe-tcp-client/	Android 原生 TCP 插件：WIFI 打印时通过 TCP 连接打印机
./pages/index/	三个 Demo 页面：蓝牙(M421)、蓝牙(通用)、WIFI

---

三、文档清单（需本地打开）

• doc/uniapp使用说明.docx — 使用说明
• doc/FW20025/uniapp Demo 开发文档.docx — Demo 开发文档（详细）
• doc/FW20025/HS-QR-YF-613-需求评估模板-...-uniapp-demo-2025-02-24.doc — 需求评估模板
• doc/FW20025/HS-QR-YF-609-功能框图-...drawio — 功能框图（draw.io）
• doc/FW20025/HS-QR-YF-610-流程图-...drawio — 流程图（draw.io）

---

四、页面与功能

1. M421 蓝牙打印 Demo（index_bt_M421.vue）

• 蓝牙类型：同时支持 经典蓝牙 与 低功耗蓝牙（BLE），按设备类型自动选择连接方式。
• 经典蓝牙：通过 components/gprint/bluetoothTool.js（依赖 Android 原生，仅 APP-PLUS）。
• 低功耗蓝牙：uni.createBLEConnection、uni.getBLEDeviceServices、uni.getBLEDeviceCharacteristics，写入用 uni.writeBLECharacteristicValue，支持 MTU 设置（22–512）。
• 流程：开蓝牙 → 扫描设备（经典 + 已配对 + BLE）→ 连接 → 生成指令/选图/PDF/Base64 → 发送打印（分包写入，带进度）。
• 打印能力：条码指令（TSC）、本地图片、本地 PDF、Base64 图、远程图片 URL；打印张数 1–10。

2. 通用蓝牙 Demo（index-bt.vue）

• 仅 低功耗蓝牙：uni.openBluetoothAdapter、uni.startBluetoothDevicesDiscovery、uni.createBLEConnection。
• 需先定位权限（部分 Android 要求）。
• 同样使用 tsc.js / esc.js 生成指令，Canvas 预览后发送。

3. WIFI 打印 Demo（index-sk.vue）

• 通过 原生插件 moe-tcp-client 连接打印机 IP + 端口（默认 9100）。
• 连接后：条码、图片、PDF、Base64 与蓝牙 Demo 类似，指令仍为 TSC/ESC，仅传输通道改为 TCP。

---

五、核心组件

1. components/gprint/tsc.js — 标签指令（TSC）

• 封装为 jpPrinter.createNew()，链式调用。
• 常用方法示例：
  • setSize(widthMm, heightMm) — 标签尺寸（mm）
  • setSpeed(1-6)、setDensity(0-15)、setGap / setGapMM — 速度、浓度、纸间隙
  • setCls、setFeed、setDirection、setReference、setHome、setFromfeed — 清缓存、走纸、方向、原点
  • setText(x, y, font, xScale, yScale, str) — 文本
  • setBar、setBox — 线条、方框
  • 条码、二维码等（见源码内注释）。
• 指令通过 addCommand 转为 GB18030 编码的字节数组，最后通过 getCommand() 取出并发送。

2. components/gprint/esc.js — 票据指令（ESC）

• 用于小票类打印，若食品标签仅打标签纸，可主要参考 TSC。

3. components/gprint/bluetoothTool.js — 经典蓝牙（仅 Android APP-PLUS）

• 依赖 plus.android，UUID 使用 SPP：00001101-0000-1000-8000-00805F9B34FB。
• 提供：开关蓝牙、搜索/取消、配对列表、连接/断开、发送字节数组、接收回调。
• 与 index_bt_M421.vue 中“经典蓝牙”分支配合使用。

4. nativeplugins/moe-tcp-client — TCP 客户端（WIFI 打印）

• 引入：uni.requireNativePlugin("moe-tcp-client")。
• 方法：connect({ip, port}, callback)、disconnect()、isConnected(callback)、sendStr、sendHexStr。
• 监听：onReceive、onDisconnect。
• 用于 WIFI 打印机（如 GP-1224T WIFI 版）。

---

六、与食品标签 App 的对接建议

1. 美国版 App（UniApp）

   • 若使用 蓝牙打印机：可复用 index_bt_M421.vue 的经典/BLE 双模式逻辑及 bluetoothTool.js（注意仅 Android；iOS 需确认经典蓝牙 API 是否可用）。
     
   • 若使用 WIFI 打印机：复用 index-sk.vue + moe-tcp-client 的 TCP 连接与发送方式。

2. 指令层

   • 标签内容（产品名、日期、保质期等）用 tsc.js 拼 TSC 指令（setSize、setText、条码/二维码等），再调用同一套“发送字节到设备”的逻辑（蓝牙写特征值 / TCP sendHexStr）。

3. 详细需求与界面流程

   • 以 doc/FW20025/uniapp Demo 开发文档.docx 及 需求评估、流程图 为准，在本地打开查看。

---

七、相关打印机

• GP-1224T：支持 WIFI 版与蓝牙版，与当前 Demo 对应。

以上为对当前打印机 SDK 下 uniapp 项目的梳理；具体业务规则与交互以 doc 内 Word 文档为准。