更新记录

1.0.0（2026-10-29）

见下方「更新记录」

平台兼容性

uni-app(5.0)

其他

精臣Niimbot蓝牙标签打印机UTS插件（jc-niimbot-printer）使用说明

基于精臣官方 JCPrintApi Android SDK（V4.1.1） 封装的 UTS 原生插件，支持精臣 K3 / K3W 等蓝牙标签打印机。封装了蓝牙扫描、连接、标签绘制（文本 / 一维条码 / 二维码 / 线条）、打印与免连接预览全流程，Promise 风格 API 开箱即用。

一、功能特性

• 官方 SDK 驱动：走精臣私有协议（JCPrintApi V4.1.1），协议兼容性与出纸稳定性有保障
• 蓝牙全流程：扫描（约 12 秒自动停止，已配对设备优先返回）→ 连接 → 打印 → 断开
• 标签绘制：文本（字号/对齐/行模式/加粗）、一维条码（CODE128 等）、二维码、线条，坐标与字号统一 mm 制
• 免连接预览：无需连接打印机即可生成 base64 PNG 预览图
• 多纸型支持：间隙纸 / 黑标纸 / 连续纸 / 透明纸 / 标牌贴；旋转 0/90/180/270；浓度 1-5；份数可设
• 权限一键申请：内置 requestBluetoothPermission，兼容 Android 12+ 与 Android 11 及以下
• Promise API：所有异步方法返回 Promise，TypeScript 类型定义完整

二、平台兼容性

开发环境要求：

• HBuilderX：^4.25
• uni-app：^3.8.3

三、安装与权限

1. 将插件目录放入项目的 uni_modules 目录下（或通过插件市场导入）。
2. 使用前调用 requestBluetoothPermission() 申请蓝牙权限（Android 12+ 为 BLUETOOTH_SCAN / BLUETOOTH_CONNECT，Android 11 及以下为定位权限）。
3. 插件已在 AndroidManifest.xml 声明所需权限，正式打包自动合并。

提示：真机调试建议制作自定义调试基座（标准基座不包含自定义 UTS 插件），正式打包（云打包 / 本地打包）自动集成。

四、快速开始

import {
  requestBluetoothPermission, startBluetoothScan, getDiscoveredDevices,
  connect, isConnected, getConnectedInfo, printLabel, previewLabel, disconnect
} from '@/uni_modules/jc-niimbot-printer';

async function printDemo() {
  // 1. 申请蓝牙权限
  const granted = await requestBluetoothPermission();
  if (!granted) { console.log('权限被拒绝'); return; }

  // 2. 开始扫描（约 12 秒系统自动停止；可轮询 getDiscoveredDevices 取结果）
  await startBluetoothScan();
  await new Promise(r => setTimeout(r, 3000));
  const devices = JSON.parse(await getDiscoveredDevices());
  // devices: [{ name, address, bonded }]
  const target = devices.find(d => d.name.toUpperCase().startsWith('K3')) || devices[0];
  if (!target) { console.log('未找到打印机'); return; }

  // 3. 连接打印机
  await connect({ address: target.address });
  console.log('已连接:', isConnected(), getConnectedInfo());

  // 4. 打印一张 50×30mm 标签：文本 + 条码 + 二维码 + 分隔线
  await printLabel({
    width: 50, height: 30,
    labelType: 1,               // 1间隙纸 2黑标纸 3连续纸 4透明纸 5标牌贴
    density: 3,                 // 打印浓度 1-5
    copies: 1,
    printMultiple: "8.0",       // K3 为 200dpi → 8.0；300dpi 用 11.81
    items: [
      { type: 'text', x: 2, y: 2, width: 30, height: 8, value: '取餐号 A001', fontSize: 7, bold: true, textAlignHorizontal: 1, lineMode: 6 },
      { type: 'barcode', x: 2, y: 12, width: 30, height: 10, value: '1234567890', codeType: 20 },
      { type: 'qrcode', x: 36, y: 12, width: 12, height: 12, value: 'https://example.com/order/123' },
      { type: 'line', x: 2, y: 26, width: 46, height: 0.5 }
    ]
  });

  // 5.（可选）免连接预览：返回 data:image/png;base64,...
  // const preview = await previewLabel({ width: 50, height: 30, items: [...] });

  // 6. 打印完成断开
  // await disconnect();
}

五、API 接口文档

5.1 基础与连接

5.2 标签打印

printLabel / previewLabel 的 options 参数：

items 元素（坐标/尺寸单位均为 mm）：

条码 codeType 枚举（参照精臣官方 SDK）：20 CODE128 / 21 UPC-A / 22 UPC-E / 23 EAN8 / 24 EAN13 / 25 CODE93 / 26 CODE39 / 27 CODEBAR / 28 ITF25。

打印错误码：1 盒盖打开 / 2 缺纸 / 3 电量不足 / 4 电池异常 / 5 手动停止(按键) / 6 数据错误 / 7 温度过高 / 8 出纸异常 / 9 正在打印 / 10 没有检测到打印头 / 11 环境温度过低 / 12 打印头未锁紧。

六、注意事项

• 精臣 K3 为 SPP 蓝牙打印机，连接使用蓝牙 MAC 地址；部分 Android 版本蓝牙扫描需要定位权限（插件已内置申请）
• 连接/打印为耗时操作，插件已在子线程执行并回调回主线程，Promise 安全
• 中文打印无需额外配置字体（SDK 内置字体）
• 需要打印多页数据时，请多次调用 printLabel 并串联 await（每次调用即完成一个完整打印任务）
• 仅支持 Android；Vue3 项目使用（Vue2、iOS、鸿蒙、小程序、uni-app x 不支持）

七、隐私与权限声明

1. 申请的权限：蓝牙（BLUETOOTH/BLUETOOTH_ADMIN，Android 11 及以下；BLUETOOTH_SCAN/BLUETOOTH_CONNECT，Android 12 及以上）、定位（ACCESS_FINE_LOCATION，Android 11 及以下蓝牙扫描必需）、网络（INTERNET/ACCESS_NETWORK_STATE/ACCESS_WIFI_STATE）。
2. 数据采集：插件不采集任何数据，蓝牙扫描、连接与打印均在本机完成，数据不上传任何服务器。
3. 广告：无。

八、更新记录

1.0.0（2026-10-29）

• 首次发布：基于精臣官方 JCPrintApi Android SDK（V4.1.1）封装
• 支持蓝牙扫描、连接/断开、文本/一维条码/二维码/线条标签绘制、标签打印与免连接预览
• Promise 风格 API + TypeScript 类型定义
• 内置蓝牙权限申请，兼容 Android 12+ 与 Android 11 及以下