更新记录

1.5.8（2026-09-07）

  • 修复 Android：success/fail 回调 ClassCast（扁平 Option 不可强转为 BaseOption；入口去掉 coerce 重建）
  • .vue 直接传对象；.uvue 须 as XxxOption；须重打自定义基座并云端传统打包
  • 不传参行为与上一版兼容

1.5.7（2026-09-07）

  • 优化 uni-app x：入口将对象字面量归一化为 Option，业务页可直接传对象调用 API，无需再写 as XxxOption
  • 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
  • 不传参行为与上一版兼容

1.5.6（2026-09-06）

  • 修复协议写帧/分片：payload.size 与下标 Number.from/toInt/toByte
  • 修复协议 byteArray 转换：size/下标 Number.from 与 toInt
  • 修复 App 端成功回调与驱动稳定性：去掉 undefined、可变属性强制解包改为局部拷贝；iOS BLE 状态/特性用 Number.from
  • 修复 Android 分片写入与 UDP 发现：ByteArray.size / getLength 先 Number.from
  • 修复 Android 运行时 ClassCastException：成功回调结果改为 UTSJSONObject 别名，避免强转为独立 SuccessResult 类型
  • 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
  • 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
  • 【务必使用此版本及以上版本打包使用，低版本存在缺陷】
查看更多

平台兼容性

uni-app(4.11)

Vue2 Vue3 Vue3插件版本 Chrome Safari app-vue app-vue插件版本 app-nvue app-nvue插件版本 Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本
× √ 1.5.6 × × √ 1.5.6 √ 1.5.6 5.0 1.5.6 12 1.5.6 12 1.5.6
微信小程序 微信小程序插件版本 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
2.22.0 1.5.6 × × × × × × × × - × ×

uni-app x(4.11)

Chrome Safari Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本 微信小程序 微信小程序插件版本
× × 5.0 1.5.6 12 1.5.6 12 1.5.6 2.22.0 1.5.6

breao-jolimarkprint 使用说明

映美（Jolimark）便携打印插件，适用于收银 / 便携票据场景。

当前版本：1.5.8

  • Android：蓝牙（经典 SPP）+ 局域网（ESC / HTML / PNG）
  • iOS：蓝牙（BLE）+ 局域网
  • 鸿蒙：蓝牙（BLE，默认 Service EE / 特征 EE01）+ 局域网（uni-app / uni-app x）
  • 微信小程序：仅 BLE（Service EE / 特征 EE01）
  • 能力：ESC 文本与字节透传、HTML / PNG、切纸 / 钱箱、状态查询、已配对设备、短打印队列与 busy、大包分片背压
  • 不做映美云 HTTP API、USB、TSC 标签设计器

建议调用顺序：init → 扫描/发现 → 连接 → 打印 → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例连接语义：再次 init 会销毁上一实例。连续打印会进入短队列串行发送；队列执行中 getConnectionState 可能返回 busy。

1. 环境要求

  • HBuilderX 4.11 及以上
  • uni-app Vue3（App-vue / App-nvue）或 uni-app x（App；微信能力与 uni-app 一致）
  • 支持：App-Android、App-iOS、App-鸿蒙、微信小程序
  • 不支持：H5 及其它小程序
  • Android 最低 API：21；iOS 最低 12；鸿蒙最低 API：12；微信小程序基础库建议 2.22.0 及以上
  • App 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包
  • 授权绑定唯一 appid + 包名

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-jolimarkprint，或从插件市场导入后同步。

import {
  init,
  destroy,
  startBluetoothScan,
  stopBluetoothScan,
  getBondedDevices,
  connectBluetooth,
  startLanDiscover,
  stopLanDiscover,
  connectLan,
  disconnect,
  printText,
  printBytes,
  printHtml,
  printImage,
  cut,
  cutPaper,
  openCashBox,
  getPrinterStatus,
  getConnectionState,
} from '@/uni_modules/breao-jolimarkprint'

3. API

3.1 init / destroy

init({
  transport: 'bluetooth', // 或 'lan'；全量见 §4
  modelHint: 'CFP-535B',
  debug: false,
  onDisconnected(res) {
    console.log(res.address)
  },
  success() {},
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

destroy({ success() {}, fail(err) {} })

3.2 蓝牙扫描与连接

startBluetoothScan({
  timeout: 10000,
  includeBonded: true,
  success(res) {
    // res.devices: [{ name, address, rssi?, bonded? }]
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

stopBluetoothScan({ success() {}, fail() {} })

getBondedDevices({ success(res) {}, fail(err) {} }) // Android / 鸿蒙已配对；其它端返回不支持

connectBluetooth({
  address: '…', // Android=MAC；iOS/微信/鸿蒙=扫描得到的 UUID / deviceId
  timeout: 15000,
  success() {},
  fail(err) {},
})

说明：请先扫描再连接（未扫描直接 connect 会返回中文错误）；参数默认值见 §4。

3.3 局域网发现与连接

startLanDiscover({
  timeout: 3000,
  success(res) {
    // res.devices: [{ name, host, deviceId?, model? }]
  },
  fail(err) {},
})

stopLanDiscover({ success() {}, fail() {} })

connectLan({
  host: '192.168.1.100',
  protocol: 'esc', // 默认 TCP 19100；'framed' → 10001
  success() {},
  fail(err) {},
})

protocol 为 esc 时调用 printHtml / printImage 会返回 9030006，请改用 framed（详见 §4.2）。

3.4 打印与收银

printText({ content: 'Hello\n第二行', success() {}, fail(err) {} })

printBytes({ data: arrayBuffer, raw: false })

printHtml({
  html: '<html><body><div>映美 HTML</div></body></html>',
  paperType: 1,
  paperWidth: 58,
})

printImage({ data: pngArrayBuffer }) // 须 PNG 原始字节

cut({ mode: 'partial', success() {}, fail() {} })
cutPaper({ mode: 'partial' }) // 等同 cut
openCashBox({ pin: 0, success() {}, fail() {} })

getPrinterStatus({
  success(res) {
    // res.online / res.rawStatus（多数机型为 -1）/ res.note
  },
})

getConnectionState({
  success(st) {
    // st.state: disconnected | connecting | connected | busy
    // st.transport / address / lanProtocol? / busy?
  },
})

disconnect({ success() {}, fail() {} })
字段 说明
state 连接状态；打印队列执行中可为 busy
online 是否已连接（getPrinterStatus）
transport 当前 init 的 bluetooth 或 lan
address 已连接设备 MAC、UUID 或 IP
lanProtocol 局域网已连接时的 esc 或 framed
busy 是否正在扫描/连接/打印

4. 可配置项

字段 位置 默认 说明
transport init bluetooth bluetooth 或 lan
modelHint init 无 机型提示，如 CFP-535B
debug init false 调试日志
bleChunkSize init iOS 180 / 微信·鸿蒙 20 BLE 分片字节数；Android SPP 忽略
bleWriteInterval init iOS 25 / 微信·鸿蒙 20 BLE 写间隔毫秒；传 0 尽量无延迟；SPP 忽略
bleServiceUuid init 映美 EE 默认 000000EE-0000-1000-8000-00805F9B34FB；SPP 忽略
bleCharacteristicUuid init 映美 EE01 默认 0000EE01-0000-1000-8000-00805F9B34FB；SPP 忽略
lanDiscoverPort init 10002 UDP 局域网发现端口
onDisconnected init 无 被动断开回调
timeout startBluetoothScan 10000 蓝牙扫描超时毫秒
includeBonded startBluetoothScan true 是否合并系统已配对设备
nameHints startBluetoothScan 内置关键字 名称过滤；空数组则用内置表（JOLIMARK/映美/CFP 等）
address connectBluetooth 必填 设备地址；Android 为 MAC，iOS/微信/鸿蒙为扫描 UUID / deviceId
timeout connectBluetooth 15000 蓝牙连接超时毫秒
timeout startLanDiscover 3000 UDP 发现超时毫秒
discoverPort startLanDiscover 继承 init 覆盖 init.lanDiscoverPort
host connectLan 必填 打印机 IP
protocol connectLan esc esc（TCP 19100）或 framed（TCP 10001）
port connectLan 随 protocol esc→19100，framed→10001；可手动覆盖
timeout connectLan 10000 局域网 TCP 连接超时毫秒
content printText 必填 待打印文本
encoding printText 分端默认 Android/iOS=GBK；鸿蒙/微信=UTF-8
data printBytes 必填 原始字节 ArrayBuffer
raw printBytes false false=封装映美 ESC 帧（蓝牙 SPP 写帧；局域网 framed 入帧）；true=原样字节透传（TCP/SPP 不封装）
html printHtml 必填 映美标准 HTML 字符串
paperType printHtml 1 纸型；主要 framed 使用
paperWidth printHtml 58 纸宽 mm；主要 framed 使用
taskId printHtml 时间戳 任务 id；主要 framed 使用
data printImage 必填 PNG 原始字节 ArrayBuffer
mode cut / cutPaper partial partial 半切 / full 全切
pin openCashBox 0 钱箱针脚 0 或 1

不传参即用默认值。

4.1 端能力摘要

能力 Android iOS 鸿蒙 微信
蓝牙 经典 SPP（MAC） BLE（UUID） BLE（deviceId，EE/EE01） BLE（deviceId）
LAN esc / framed / UDP 支持 支持 支持 不支持
HTML / PNG 支持 支持 须 framed / BLE 写帧 蓝牙写帧
getBondedDevices 支持 不支持 支持 不支持
切纸 / 钱箱 ESC 通道 ESC 通道 ESC 通道 ESC 通道

4.2 局域网 protocol

protocol 默认端口 适用
esc 19100 ESC 文本 / 字节透传
framed 10001 HTML / PNG / 带帧 ESC

5. 完整示例

5.1 蓝牙（App / 微信）

import {
  init,
  startBluetoothScan,
  connectBluetooth,
  printText,
  disconnect,
  destroy,
} from '@/uni_modules/breao-jolimarkprint'

init({
  transport: 'bluetooth',
  success() {
    startBluetoothScan({
      timeout: 10000,
      success(res) {
        const d = res.devices && res.devices[0]
        if (!d) return
        connectBluetooth({
          address: d.address,
          success() {
            printText({
              content: 'Hello Jolimark',
              success() {
                disconnect({ success() { destroy({}) } })
              },
            })
          },
        })
      },
    })
  },
})

5.2 局域网（App / 鸿蒙）

import {
  init,
  connectLan,
  printHtml,
  disconnect,
  destroy,
} from '@/uni_modules/breao-jolimarkprint'

init({
  transport: 'lan',
  success() {
    connectLan({
      host: '192.168.1.100',
      protocol: 'framed',
      success() {
        printHtml({
          html: '<html><body><div>Hello</div></body></html>',
          paperWidth: 58,
          success() {
            disconnect({ success() { destroy({}) } })
          },
        })
      },
    })
  },
})

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于连接映美打印机并发送打印数据。

平台 权限 说明
Android android.permission.BLUETOOTH、android.permission.BLUETOOTH_ADMIN API≤30 蓝牙基础
Android android.permission.BLUETOOTH_SCAN、android.permission.BLUETOOTH_CONNECT Android 12+ 扫描与连接
Android android.permission.ACCESS_FINE_LOCATION、android.permission.ACCESS_COARSE_LOCATION 蓝牙扫描常见要求
Android android.permission.INTERNET、android.permission.ACCESS_NETWORK_STATE、android.permission.ACCESS_WIFI_STATE、android.permission.CHANGE_WIFI_MULTICAST_STATE 局域网发现与 TCP 打印
iOS NSBluetoothAlwaysUsageDescription、NSBluetoothPeripheralUsageDescription 蓝牙连接说明
iOS NSLocalNetworkUsageDescription 局域网打印机发现与连接
鸿蒙 ohos.permission.INTERNET 局域网 TCP 打印
鸿蒙 ohos.permission.ACCESS_BLUETOOTH、ohos.permission.DISCOVER_BLUETOOTH、ohos.permission.MANAGE_BLUETOOTH 蓝牙扫描与连接
微信 openBluetoothAdapter、startBluetoothDevicesDiscovery、createBLEConnection、getBLEDeviceServices、getBLEDeviceCharacteristics、writeBLECharacteristicValue BLE 扫描、连接与写入；需用户授权蓝牙

7. 错误码（903）

码 含义
9030001 成功
9030002 失败
9030003 未 init
9030004 蓝牙未开启或权限问题
9030005 未连接打印机
9030006 参数无效（含 LAN 非 framed 却调 HTML/PNG）
9030007 当前平台不支持
9030008 驱动无法创建
9030009 transport 不匹配
9030010 能力未实现

8. 平台注意

  • uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.5.8+ 并重打自定义基座
  • 请先扫描再连接；未扫描直接 connectBluetooth 会返回中文错误（iOS / 微信 / 鸿蒙 address 为 UUID / deviceId）
  • Android 蓝牙为经典 SPP；局域网打印时手机与打印机须同一网段，避免 AP 隔离
  • 鸿蒙支持 transport=bluetooth（BLE）与 lan；BLE 默认映美 EE / EE01；printText 默认 UTF-8，GBK 内容请用 printBytes
  • 切纸 / 钱箱走 ESC（GS V / ESC p）；蓝牙封装映美 ESC 帧；LAN esc 透传；LAN framed 以 ESC 类型入帧（机型若不支持切刀/钱箱以真机为准）
  • 大 HTML / PNG 在 LAN / SPP 按约 4KB 分片发送；BLE 仍按 bleChunkSize 分片
  • printImage 须传 PNG 原始字节，勿直接传 JPEG
  • 局域网 esc 协议下 HTML/PNG 会报 9030006，请切换 connectLan({ protocol: 'framed' })
  • 切换 transport 或释放资源时请 disconnect 后 destroy，再重新 init
  • 短打印队列深度为 32；printText / printBytes / printHtml / printImage 等打印 API 串行入队
  • 队列已满时 fail 返回 9030002，errMsg 为「打印队列已满，请稍后重试」
  • init（含再次 init）、disconnect、destroy 会清空尚未执行的队列任务

隐私、权限声明

1. 本插件需要申请的系统权限列表：

Android： android.permission.BLUETOOTH、android.permission.BLUETOOTH_ADMIN（API≤30）； android.permission.BLUETOOTH_SCAN、android.permission.BLUETOOTH_CONNECT（Android 12+）； android.permission.ACCESS_FINE_LOCATION、android.permission.ACCESS_COARSE_LOCATION（蓝牙扫描辅助）； android.permission.INTERNET、android.permission.ACCESS_NETWORK_STATE、android.permission.ACCESS_WIFI_STATE、android.permission.CHANGE_WIFI_MULTICAST_STATE（局域网发现与 TCP 打印）。 iOS： NSBluetoothAlwaysUsageDescription、NSBluetoothPeripheralUsageDescription、NSLocalNetworkUsageDescription。 鸿蒙： ohos.permission.INTERNET、ohos.permission.ACCESS_BLUETOOTH、ohos.permission.DISCOVER_BLUETOOTH、ohos.permission.MANAGE_BLUETOOTH。 微信小程序： 蓝牙能力（openBluetoothAdapter、startBluetoothDevicesDiscovery、createBLEConnection、getBLEDeviceServices、getBLEDeviceCharacteristics、writeBLECharacteristicValue；需用户授权蓝牙）。 用途：映美打印机扫描、连接与打印数据传输。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

不采集、不上传任何数据；打印内容仅经本机蓝牙或局域网发至已连接的映美打印机。协议实现仅用于本地设备通信

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。