更新记录

2.0.0（2025-08-15） 下载此版本

1、UTS插件上线

平台兼容性

uni-app(4.66)

uni-app x(4.66)

精臣 UTS SDK 开发文档

一、使用说明

1. 使用插件需要申请对应蓝牙权限

/** Android **/
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> 
// Android 12
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/> 
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>

2. 接入示例：（详细使用方法可以参照插件示例项目）

// 导入UTS插件
import {JCPrinter} from '@/uni_modules/niimbot-jcsdk';

// 初始化SDK
jcapi.initSDK()

// 搜索蓝牙设备
// 需要开发者先获取蓝牙和定位权限（部分Android版本需要定位权限才能使用蓝牙）
jcapi.getBluetoothDevices(function(r) {
    // 会搜索附近所有蓝牙设备，可以根据名称自行筛选过滤
    console.log("device:" + JSON.stringify(r))
})
// 或者搜索指定的一个或多个机型（蓝牙名称前缀匹配，不区分大小写）
// jcapi.getBluetoothDevicesWithName({
//          "name": ["b32", "B21"] // 添加需要过滤的机型
// },function(r){
//          console.log("device:" + JSON.stringify(r))
// })

// 连接蓝牙打印机
jcapi.openPrinterByDevice({
    address: item.address,
    name: item.name
    deviceType: 0
}, function(r) {
    if(r.code == 0) { // 连接成功 }
})

/* 
// 蓝牙配网
jcapi.configWifi({
    wifiName:"wifi名称", //只支持2.4GHz
    wifiPwd:"wifi密码",
  }, function(r){
    if (r.code == 0) { //success}
  }
});

// 搜索局域网打印机
jcapi.getWifiDevices(function(r){
    console.log("device:" + JSON.stringify(r))
})

// 连接局域网打印机
jcapi.openPrinterByDevice({
    address: item.address,
    name: item.name
    deviceType: 1
}, function(r) {
    if(r.code == 0) { // 连接成功 }
})
*/

// 监听打印页码回调
jcapi.didReadPrintCountInfo(function(r) { console.log(r) })

// 监听打印错误回调
jcapi.didReadPrintErrorInfo(function(r) { console.log(r) })

// 初始化画板
jcapi.initDrawingBoard({ width: 40, height: 20, rotate: 0 });

// 绘制文字
jcapi.drawLabelText({
    x: 2,
    y: 2,
    width: 30,
    height: 20,
    value: "打印插件",
    fontSize: 4,
    lineMode: 1,
    lineSpace: 0,
    letterSpace: 0,
    roate: 0,
    textAlignHorizontal: 1,
    textAlignVertical: 1,
})

// 生成打印数据
let imageJsonObj = jcapi.generateLabelJson()

// 预览打印数据
let previewJsonObj = jcapi.generatePrintPreviewImage(imageJsonObj)

// 设置打印任务
jcapi.startJob({
    totalCount: 1,
    density: 5,
    labelType: 2,
    printMode: 1,
},function(r){
    if(r.code == 0) { // 设置成功，开始发送打印数据
        // 发送打印数据
        jcapi.printData(
            imageJsonObj,
            {"printQuantity": 1,}, 
            function(r) {
                if (r.code == 0) { console.log("打印成功") }
            }
        )
    }
})

二、接口文档

2.1 基础功能

2.1.1 初始化SDK

/**
 * 初始化SDK
 * （使用SDK之前必须先执行初始化）
 */
initSDK()

2.1.2 搜索打印机

搜索蓝牙打印机

/**
 * 搜索蓝牙打印机（返回搜索到的所有蓝牙设备）
 * @callback callback 搜索接口回调
 *            [{"name": "", "address": "", rssi:""}, ...]
 *            // iOS 只有 name 字段有效
 */
getBluetoothDevices(callback)

/**
 * 搜索过滤指定的蓝牙打印机类型
 * @para {{}} data
 * @para {array} data.name 过滤名称，数组类型数据，可以设置多个过滤。
 *                         通过蓝牙名称前缀过滤，不区分大小写。
 *                           示例：
 *                                  {"name": ["B21"]}  //过滤B21机型
 *                                  {"name": ["B21", "B3S"]} //过滤B21和B32机型
 * @callback callback 蓝牙回调
 *            [{"name": "", "address": "", rssi:""}]
 *            // iOS 只有 name 字段有效
 */
getBluetoothDevicesWithName(data, callback)

搜索WiFi打印机

/**
* 搜索局域网打印机
* @callback 搜索结果回调
*                   [{“name”: "", address: "", "rssi": ""}, ...]
*           // 局域网打印机没有rssi数值
*/
getWifiDevices(callback)

2.1.3 连接打印机

/**
 * 连接打印机
 * @param {{}} data 连接参数（iOS 使用蓝牙名称连接，Android 使用蓝牙地址连接），使用时一般直接使用搜索接口返回的数据
 * @param {string} data.address 打印机蓝牙MAC地址 或 局域网打印机的ip地址
 * @param {string} data.name 打印机蓝牙名称（局域网打印机可为空）
 * @param {number} data.deviceType 打印机类型
 *                               0: 蓝牙打印机， 1: 局域网打印机
 * @callback callback 回调
 *                  {"code": 0} // 0: 成功， -1: 失败
 */
openPrinterByDevice(data, function(r) {

})

2.1.4 断开连接

/**
    * 断开打印机
    */
close()

2.1.5 异常回调

/**
 * 监听当前任务打印异常回调
 * @callback callback 异常回调
 *            {"code": errorCode} // 错误类型
 * 异常类型：
  1-盒盖打开
  2-缺纸
  3-电量不足
  4-电池异常
  5-手动停止（按键）
  6-数据错误
  7-温度过高
  8-出纸异常
  9-正在打印  
  10-没有检测到打印头  
  11-环境温度过低  
  12-打印头未锁紧
  13-未检测到碳带  
  14-不匹配的碳带  
  15-用完的碳带  
  16-不支持的纸张类型
  17-纸张类型设置失败
  18-打印模式设置失败
  19-设置浓度失败
  20-写入rfid失败
  21-边距设置失败
  22-通讯异常
  23-打印机连接断开
  24-画板参数错误
  25-旋转角度错误
  26-json参数错误
  27-出纸异常（B3S）
  28-检查纸张类型
  29-RFID标签未进行写入操作
  30-不支持浓度设置
  31-不支持的打印模式
 */
didReadPrintErrorInfo(function(r) {

})

2.1.6 打印进度回调

/**
 * 当前任务打印进度回调
 * @callback callback 打印进度回调
 *                  {"count": number} // 已打印标签数
 */
didReadPrintCountInfo(function(r) {

})

2.1.7 蓝牙配网

在蓝牙成功连接的情况下给支持局域网打印的打印机配置网络。

/**
* 打印机配网接口
* @para {{}} data 配网参数
* @para {string} data.wifiName wifi名称（只支持2.4GHz）
* @para {string} data.wifiPwd wifi密码
* @callback 配网结果回调
*            {"code": 0} // 0: 成功， -1: 失败， -3: 不支持
*/
configWifi(data, callback)

注意：

1. 只能在蓝牙下给打印机配网，WiFi连接下无法调用配网
2. 只有部分机型支持局域网打印，且只能使用2.4GHz的网络

2.2 绘制

2.2.1 初始化绘制

/**
 * 初始化绘制
 * @param {{}} data 绘制参数
 * @param {number} data.width 画板宽度，单位mm
 * @param {number} data.height 画板高度，单位mm
 * @param {number} data.rotate （可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180。
 */
initDrawingBoard(data)

2.2.2 绘制文本

/**
 * 绘制文本
 * @param {{}} data 绘制参数
 * @param {number} data.x 元素起始x坐标
 * @param {number} data.y 元素起始y坐标
 * @param {number} data.width 文本框宽度，单位mm
 * @param {number} data.height 文本框高度，单位mm
 * @param {string} data.value 绘制文字内容
 * @param {number} data.fontSize 字体大小，单位mm。默认高度4mm。
 * @param {number} data.rotate（可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180、270。
 * @param {number} data.lineMode 换行方式，默认为2。
 *                               1:宽⾼固定，内容⼤⼩⾃适应（字号/字符间距/⾏间距，按⽐例缩放）
 *                               2:宽度固定，⾼度⾃适应 
 *                               6.宽⾼固定，内容超过预设的宽⾼时⾃动缩⼩
 * @param {number} data.letterSpace 字间隔。默认为0。
 * @param {number} data.lineSpace ⾏间隔。默认为0。
 * @param {number} data.textAlignHorizontal 文字水平布局，默认为1。
 *                                          0：左对齐
 *                                          1：水平居中
 *                                          2：右边对齐
 * @param {number} data.textAlignVertical 文字垂直布局，默认为1。（备注：换行模式为2时无效）
 *                                          0：顶部对齐
 *                                          1：垂直居中
 *                                          2：底部对齐
 */
drawLabelText(data)

2.2.3 绘制条形码

/**
 * 绘制条形码
 * @param {{}} data 绘制参数
 * @param {number} data.x 元素起始x坐标
 * @param {number} data.y 元素起始y坐标
 * @param {number} data.width 条码宽度，单位mm
 * @param {number} data.height 条码高度，单位mm
 * @param {string} data.value 条码内容
 * @param {number} data.fontSize 字体大小，单位mm。默认4mm。
 * @param {number} data.rotate（可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180、270。
 * @param {number} data.codeType 条码类型。默认类型20。
 *                           20:CODE128
 *                           21:UPC-A
 *                           22:UPC-E
 *                           23:EAN8
 *                           24:EAN13
 *                           25:CODE93
 *                           26:CODE39
 *                           27:CODEBAR
 *                           28:ITF25
 * @param {number} data.textHeight 文本高度。默认高度4mm。
 * @param {number} data.textPosition 条码文本位置。默认为0。
 *                      0: 下方显示
 *                      1: 上方显示
 *                      2: 不显示
 */
drawLabelBarCode(data)

2.2.4 绘制二维码

/**
 * 绘制二维码
 * @param {{}} data 绘制参数
 * @param {number} data.x 元素起始x坐标
 * @param {number} data.y 元素起始y坐标
 * @param {number} data.width 二维码宽度，单位mm
 * @param {number} data.height 二维码高度，单位mm
 * @param {string} data.value 二维码内容
 * @param {number} data.rotate（可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180、270。
 * @param {number} data.codeType 二维码类型，默认类型31。
 *                                                      31:QR_CODE
 *                                                      32:PDF417
 *                                                      33:DATA_MATRIX
 *                                                      34:AZTEC
 */
drawLabelQrCode(data)

2.2.5 绘制线条

/**
 * 绘制线条
 * @param {{}} data 绘制参数
 * @param {number} data.x 元素起始x坐标
 * @param {number} data.y 元素起始y坐标
 * @param {number} data.width 线条宽度，单位mm
 * @param {number} data.height 线条高度，单位mm
 * @param {number} data.rotate（可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180、270。
 * @param {number} data.lineType 线条类型，默认类型为1。
 *                                                                  1: 实线 ，2:虚线
 */
drawLabelLine(data)

2.2.6 绘制形状

/**
 * 绘制形状
 * @param {{}} data 绘制参数
 * @param {number} data.x 元素起始x坐标
 * @param {number} data.y 元素起始y坐标
 * @param {number} data.height 线条高度，单位mm
 * @param {number} data.graphType 图像类型，默认类型为1。1: 圆形，2: 椭圆， 3:矩形， 4: 圆角矩形 
 * @param {number} data.rotate（可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180、270。
 * @param {number} data.cornerRadius 圆角半径，单位mm
 * @param {number} data.lineWidth 线条宽，单位mm。默认线宽为0.2mm。
 * @param {number} data.lineType 线条类型，默认类型为1。1: 实线，2: 虚线
 */
drawLabelGraph(data)

2.2.7 绘制图片

/**
 * 绘制图片
 * @param {{}} data 绘制参数
 * @param {number} data.x 元素起始x坐标
 * @param {number} data.y 元素起始y坐标
 * @param {number} data.width 图片宽度，单位mm
 * @param {number} data.height 图片高度，单位mm
 * @param {number} data.rotate（可选）画板旋转角度，默认为0，不旋转。支持的旋转角度 0、90、180、270。
 * @param {number} data.imageProcessingType （可选）处理算法，默认为1
 * @param {number} data.imageProcessingValue （可选）阈值，默认127
 */
drawLabelImage(data)

2.2.8 生成绘制数据

生成打印数据。提交的打印数据 printData 接口的打印数据参数使用此接口返回的数据。

/**
 * 生成绘制内容
 * @return {{}} 绘制内容json对象
 */
generateLabelJson()

2.2.9 预览数据

/**
* 预览数据
* @para data {{}} 接口“generateLabelJson()”返回的数据
* @return 返回接口
*         {"base64": "（预览图片base64编码）"} // 成功
*         {"base64": ""} // 失败
*/
generatePrintPreviewImage(data)

2.3 打印

2.3.1 设置打印任务

/**
 * 设置打印任务
 * @param {{}} config
 * @param {number} config.totalCount 打印总数
 * @param {number} config.density 打印浓度
 * @param {number} config.labelType 标签类型
 *                  1：间隙纸
 *                  2：黑标纸
 *                  3：连续纸
 *                  4：定孔纸
 *                  5：透明纸
 * @param {number} config.printMode 打印模式
 *                  1：热敏
 *                  2：热转印
 * 
 * @callback callback 设置打印任务回调
 *                    {'code': 0} // 0: 成功， -1: 失败
 */
startJob(config, function(r) {
    if (r.code) {
      console.log("startJob success")
    } else {
      console.log("startJob fail")
    }
})

2.3.2 提交打印数据

/**
 * 提交打印数据
 * @param {{}} imageJson 打印数据，使用函数 funtion generateLabelJson() 返回的数据
 * @param {{}} imageConfig 打印数据参数 
 * @param {number} imageConfig.printQuantity 当前数据打印份数
 * @callback callback 数据提交回调
 *                                {'code': 0} // // 0: 成功， -1: 失败
 */
printData(imageJson, imageConfig, function(r) {
    if (r.code) {
      console.log("printData success")
    } else {
      console.log("printData fail")
    }
})

注：同一个打印任务中需要打印多页数据时，需要等待上一个打印数据的成功回调再继续发送。

2.3.3 取消打印

用于打印过程中取消打印

cancelJob()

2.3.4 检测设备连接

检测是否有设备连接

/**
 * 检测设备连接
 * @return {{}}
 *        {'value': 0}  // 0: 没有连接设备， 1: 有连接设备
 */
JSONObject isConnected()