# 打印机 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. 引入组件**

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

**2. 创建指令对象**

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

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

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

```js
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 指令编程（标签模式）**

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

```js
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 官方 [定位](https://uniapp.dcloud.net.cn/api/location/location.html)、[蓝牙](https://uniapp.dcloud.net.cn/api/system/bluetooth.html)。
- **注意**：
  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 文档为准。