更新记录

1.0.0（2026-07-19）

首发：自研高性能原生打印核心：把票据/标签文档模型渲染为 ESC/POS(小票)/TSPL(标签)/ZPL II(Zebra 标签)指令字节，配薄 JS 蓝牙助手经

平台兼容性

uni-app x(5.14)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
×	×	5.0	12	×	×

nex-printer —— 高性能蓝牙打印（ESC/POS + TSPL + ZPL）

自研高性能原生打印核心：把「票据 / 标签文档模型（JSON）」渲染为 ESC/POS（小票）/ TSPL（标签）/ ZPL II（Zebra 标签）三套指令字节流，提供 uni-app 可调的 JS API。配一层纯 JS 蓝牙助手经 uni 内置 BLE 发送。 仅支持 App 端（Android / iOS），H5 / 小程序加载不了原生库。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。 调用形态：documentJson(string) 进 / RenderResult(base64 + number) 出——文档 JSON 字符串进，结果含 base64 指令字节流（适合 BLE 分包发送）。自研核心，内置 GBK 中文编码与 CJK 列宽处理，无额外系统依赖。

API

JS API	签名	说明
`render`	`render(documentJson): RenderResult`	渲染文档 JSON 为指令字节流，base64 返回。`dialect` 支持 `"escpos"` / `"tspl"` / `"zpl"`
`renderToFile`	`renderToFile(documentJson, destPath): RenderFileResult`	渲染并写入文件（大栅格图片场景，避免大 base64 跨语言传输），返回元信息
`renderZpl`	`renderZpl(documentJson): RenderResult`	便捷入口：按 ZPL II（Zebra 标签）渲染，等价于 `dialect="zpl"` 调 `render`（JSON 仍需带合法 `dialect` 字段）

类型

// render / renderZpl 返回（字段 camelCase）
type RenderResult = { base64: string; byteLength: number; dialect: string; costMs: number };
// renderToFile 返回
type RenderFileResult = { byteLength: number; dialect: string; costMs: number };

错误经原生层 PrinterException(Kotlin) / PrinterError(Swift) 抛出，UTS 侧透传：InvalidParam / Decode / Io / Unsupported。

三方言能力

escpos：58/80mm 小票（ESC @ 初始化 + GBK 中文模式，text/columns/divider/qrcode/barcode/内置图像编解码/feed/cut/cashdrawer/raw）。
tspl：标签机（SIZE/GAP/CLS … PRINT，y 坐标自动累加，cut/cashdrawer → Unsupported）。
zpl：Zebra 标签（^XA … ^XZ，^PW/^LL/^MD/^PQ；Code128 ^BC、QR ^BQ、内置图像编解码/CJK 文本走 ^GFA 图形域）。

用法

import { render, renderZpl } from "@/uni_modules/nex-printer";

// ESC/POS 小票
const receipt = JSON.stringify({
  dialect: "escpos", widthDots: 384,
  blocks: [
    { kind: "text", text: "门店小票", align: "center", bold: true },
    { kind: "columns", cols: [{ text: "商品", width: 8 }, { text: "9.9", width: 6, align: "right" }] },
    { kind: "cut", mode: "full" }
  ]
});
const r1 = render(receipt);
console.log(r1.dialect, r1.byteLength, r1.base64);

// ZPL II 标签（Zebra）：40×30mm，条码 + 二维码
const zpl = JSON.stringify({
  dialect: "zpl", label: { widthMm: 40, heightMm: 30, gapMm: 2, copies: 1, density: 10 },
  blocks: [
    { kind: "text", text: "SKU-001" },
    { kind: "barcode", data: "ABC123", symbology: "code128", height: 80, hri: true },
    { kind: "qrcode", data: "https://example.com", size: 5, ecLevel: "Q" }
  ]
});
const r2 = renderZpl(zpl); // 或 render(zpl)，dialect 已是 "zpl"
console.log(r2.dialect); // "zpl"

ZPL 中文边界（重要）

ZPL 内置字体不含 CJK 字形，本插件也不内置字体渲染。故 text 块含中文/非 ASCII 时走「占位图形」：按字符显示宽度把每字符画成一个空心方框（tofu）打包成 1-bit 位图以 ^GFA 发送——这是几何占位，非真实字形。

生产中文标签：在 JS 侧把文本预渲染为图片（PNG/位图）后用内置图像编解码块——内置图像编解码 → ^GFA 是真实可用的中文打印路径（图片真实解码 + Floyd–Steinberg 抖动 + ZPL 图形域编码）。

蓝牙助手

插件附带纯 JS 蓝牙助手（helper/）：PrinterDoc 文档构造器 + connectPrinter / sendBytes / printDocument，经 uni 内置 BLE 把指令字节流分包发给打印机，开箱即用。

平台与调试边界

仅 app-android / app-ios；H5、各家小程序不支持。
含原生库 → 真机运行需自定义调试基座（或云打包）。
iOS 端含 Swift 组件，宿主原生工程需开启「支持 Swift」。
完整契约见 docs/printer-plugin-contract.md。