更新记录

1.1.0（2026-11-05）

• 首发：可视化小票模板编辑器（文本/二维码/条码/图片/分隔线）+ ESC/POS 指令生成。
• 蓝牙/网口打印（UTS 原生）、中文自动点阵（canvas 位图），模板导出 JSON 复用。
• 深度增强：模板双花括号变量与默认值（Pro）、打印前自检（纸宽/元素/条码 ASCII/二维码尺寸校验）、纸张用量预估与按纸宽自动折行（Pro）、幂等打印队列（业务单号去重/限次重试，Pro）；免费版模板元素上限 30。
• 1.1.0 结构调整：改为 UTS API 插件（type=uts），可视化编辑器拆分为独立插件 zl-pos-editor；新增根 index.uts 统一导出（printBytes/printTemplate/buildEscPos/generate/createTemplate 等）。

平台兼容性

uni-app(4.0)

POS 打印引擎 Pro（zl-pos-print）

简介

uni-app UTS 打印引擎（API 插件）：小票模板数据模型 + ESC/POS 指令生成 + 蓝牙/网口打印（UTS 原生）。以纯 API 调用：定义模板（文本/二维码/条码/图片/分隔线）→ 生成 ESC/POS 指令字节 → 经蓝牙或网口发送至热敏打印机。中文自动点阵（canvas 位图，跨机型可靠），模板可序列化 JSON 复用。仅 App 端。

配套免费组件插件 zl-pos-editor（小票模板编辑器）提供可视化设计界面；本引擎负责指令生成与打印。

功能特性

• 模板变量（Pro）：双花括号变量 + 默认值，文本/二维码/条码自动填充，缺失变量提示
• 打印前自检：纸宽/元素/条码/二维码/图片/id 重复全面校验，阻断损坏指令
• 纸张预估（Pro） 与 按纸宽折行（中文全角/ASCII 半角）
• 幂等打印队列（Pro）：业务单号去重、失败限次重试、人工重打，杜绝重复出票
• 模板数据模型：文本/二维码/条码/图片/分隔线元素，序列化 JSON 复用
• 一键生成 ESC/POS 指令字节
• 蓝牙（BLE/SPP）与网口(TCP)打印
• 断线透明重连 + 分块写入
• 中文点阵位图，免字库依赖

平台兼容

App-Android、App-iOS（仅 App，不涉及 H5/小程序）

快速上手

import { createTemplate, newElement, printTemplate } from '@/uni_modules/zl-pos-print'

// 1) 构造模板（也可由 zl-pos-editor 导出 JSON 后 deserialize 导入）
const tpl = createTemplate('测试小票', 384)        // 纸宽 384 点（58mm）
tpl.elements.push(newElement('text'))             // 文本元素（可设 content/align/size/bold）
tpl.elements.push(newElement('line'))             // 分隔线
tpl.elements.push(newElement('qrcode'))           // 二维码

// 2) 一键生成 ESC/POS 并发送（target：蓝牙MAC 或 IP:端口）
await printTemplate({ target: '192.168.1.50:9100', template: tpl })

模板含图片元素时，图片位图需画布上下文，请用 generate(tpl, { canvas, ctx, images }) 生成字节后调用 printBytes({ target, bytes })。

Android 权限与配置

• BLUETOOTH_CONNECT / BLUETOOTH_SCAN（Android 12+，系统弹窗授权）
• BLUETOOTH / BLUETOOTH_ADMIN（Android 11 及以下）
• INTERNET（网口打印）
• 蓝牙权限在 manifest.json → App 模块/权限中勾选。

iOS 配置

网口打印使用 TCP；蓝牙打印需 MFi 外设并在 Info.plist 声明 UISupportedExternalAccessoryProtocols。

合规声明

仅将小票内容以 ESC/POS 指令发送至用户指定的打印机，不上传任何小票内容或业务数据到插件作者服务器。自研 ESC/POS 实现，无第三方闭源 SDK。

常见问题

• Q：连不上蓝牙？ A：确认已配对且授予蓝牙权限；低版本 Android 需位置权限用于扫描。
• Q：中文乱码？ A：已采用 canvas 点阵位图，无需打印机内置字库。
• Q：怎么可视化编辑模板？ A：安装免费插件 zl-pos-editor，用其导出模板 JSON 后交由本引擎打印。

更新说明

1.0.0 首发：模板模型、ESC/POS 生成、蓝牙/网口打印、断线重连。 1.1.0 深度增强：模板变量自动填充、打印前自检、纸张用量预估、按纸宽折行、业务单号幂等打印队列与重打（Pro）。 1.1.0 结构调整：改为 UTS API 插件（type=uts），可视化编辑器拆分为独立免费插件 zl-pos-editor。