更新记录

1.1.6（2026-09-07）

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

1.1.5（2026-09-07）

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

1.1.4（2026-09-06）

• 修复 Android 搜索通道枚举：channels.size() 先 Number.from，get 下标 toInt
• 修复 Android 运行时 ClassCastException：成功回调结果改为 UTSJSONObject 别名，避免强转为独立 SuccessResult 类型
• 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

平台兼容性

uni-app(4.11)

uni-app x(4.11)

其他

breao-brotherprint 使用说明

兄弟 Brother 标签 / 便携打印插件，封装官方 Print SDK v4，适用于 QL / PT 系列图像、PDF 与模板打印。

当前版本：1.1.6

• Android：Wi-Fi、经典蓝牙、BLE、USB Host
• iOS：Wi-Fi、MFi 蓝牙、BLE
• 能力：printImage / printPDF / printTemplate、状态与取消、序列号与电量；连接态含 busy
• 不做鸿蒙 / 微信、固件大批量 transfer、Scanner SDK

建议调用顺序：init → openChannel（或先 startSearch）→ printImage / printPDF / printTemplate → closeChannel / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。插件为单例通道语义：再次 init 或 openChannel 会关闭上一通道。

1. 环境要求

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

2. 安装与引入

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

import {
  init,
  destroy,
  openChannel,
  closeChannel,
  startSearch,
  stopSearch,
  updatePrintSettings,
  printImage,
  printPDF,
  printTemplate,
  getPrinterStatus,
  cancelPrinting,
  requestSerialNumber,
  requestBatteryInfo,
  getConnectionState,
} from '@/uni_modules/breao-brotherprint'

3. API

3.1 init / destroy

init({
  series: 'QL',
  printerModel: 'QL_820NWB',
  labelSize: 'RollW62',
  autoCut: true,
  success() {},
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

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

3.2 打开 / 关闭通道

openChannel({
  type: 'wifi',
  address: '192.168.1.100',
  success(res) {
    // res.state / res.address / res.channelType
  },
  fail(err) {},
})

openChannel({ type: 'bluetooth', address: 'XX:XX:XX:XX:XX:XX' })
openChannel({ type: 'ble', address: 'XX:XX:XX:XX:XX:XX' })
openChannel({ type: 'usb' }) // 仅 Android

closeChannel({ success() {}, fail() {} })

3.3 搜索

startSearch({
  type: 'bluetooth',
  success(res) {
    // res.devices: [{ name, address, channelType, modelName? }]
  },
  fail(err) {},
})

// Android USB：搜索后 openChannel
startSearch({
  type: 'usb',
  success(res) {
    const d = res.devices && res.devices[0]
    if (!d) return
    openChannel({ type: 'usb' }) // address 可空；系统 USB Host 授权后连接
  },
  fail(err) {},
})

stopSearch({ success() {}, fail() {} })

说明：Android 的 bluetooth / usb 搜索可用；wifi / ble 异步搜索在 1.0.0 引导用已知 address 直连。参数见 §4。

3.4 打印设置

updatePrintSettings({
  series: 'PT',
  printerModel: 'PT_P910BT',
  labelSize: 'Width24mm',
  autoCut: true,
})

3.5 printImage / printPDF / printTemplate

printImage({ path: '/path/to/label.png', success() {}, fail(err) {} })
printImage({ paths: ['/a.png', '/b.png'], success() {}, fail(err) {} })

printPDF({ path: '/path/to/doc.pdf', success() {}, fail(err) {} })
printPDF({ path: '/path/to/doc.pdf', pages: [1, 2], success() {}, fail(err) {} })

printTemplate({
  key: 1,
  replacers: [
    { name: 'title', value: '货架A' },
    { index: 2, value: 'SN001', encode: 'UTF_8' },
  ],
  numCopies: 1,
  success() {},
  fail(err) {},
})

3.6 状态与设备信息

getPrinterStatus({
  success(res) {
    // errorCode / model / statusError
  },
  fail(err) {},
})

cancelPrinting({ success() {}, fail() {} })

requestSerialNumber({
  success(res) {
    // serialNumber
  },
  fail(err) {},
})

requestBatteryInfo({
  success(res) {
    // batteryChargeLevel / batteryHealthLevel / batteryHealthStatus
  },
  fail(err) {},
})

getConnectionState({
  success(res) {
    // state: disconnected | connecting | connected | busy
    // address / channelType / inited / busy
  },
  fail(err) {},
})

4. 可配置项

不传参即用默认值。

4.1 常用 labelSize

4.2 replacer 字段

4.3 模板打印上手

1. 用 Brother P-touch Editor（或机型配套工具）制作模板，并预先传输/安装到打印机；本插件只按 key 调机内模板，不负责上传 .lbx 等模板文件。
2. 模板内可编辑对象须命名（如 title、barcode）；replacers 用同名 name 替换，或用 index（从 0 起，与 SDK 对象顺序一致）。name 与 index 同时给时优先 name。
3. key 为机内模板编号（从 1 起），与打印机菜单/SDK 文档中的 Template Key 一致；找不到 key 时 SDK 返回打印错误（9090010）。
4. 中文内容优先 encode: 'UTF_8'；部分旧机型/地区模板可能需要 SHIFT_JIS 或 GB_18030_2000。
5. 建议流程：init（确认 series / printerModel / labelSize）→ openChannel → printTemplate → getPrinterStatus（可选）→ closeChannel。

模板最小示例：

printTemplate({
  key: 1,
  numCopies: 1,
  replacers: [
    { name: 'title', value: '货架A-01', encode: 'UTF_8' },
    { name: 'sku', value: 'SKU-10086' },
  ],
  success() {},
  fail(err) { console.error(err.errCode, err.errMsg) },
})

5. 完整示例

import {
  init,
  openChannel,
  printImage,
  getPrinterStatus,
  closeChannel,
  destroy,
} from '@/uni_modules/breao-brotherprint'

init({
  series: 'QL',
  printerModel: 'QL_820NWB',
  labelSize: 'RollW62',
  autoCut: true,
  success() {
    openChannel({
      type: 'wifi',
      address: '192.168.1.100',
      success() {
        printImage({
          path: '/path/to/label.png',
          success() {
            getPrinterStatus({
              success() {
                closeChannel({ success() { destroy({}) } })
              },
            })
          },
          fail(err) {
            console.error(err.errCode, err.errMsg)
          },
        })
      },
      fail(err) {
        console.error(err.errCode, err.errMsg)
      },
    })
  },
})

5.1 模板打印完整路径

import {
  init,
  openChannel,
  printTemplate,
  closeChannel,
  destroy,
} from '@/uni_modules/breao-brotherprint'

init({
  series: 'QL',
  printerModel: 'QL_820NWB',
  labelSize: 'RollW62',
  success() {
    openChannel({
      type: 'wifi',
      address: '192.168.1.100',
      success() {
        printTemplate({
          key: 1,
          replacers: [
            { name: 'title', value: '示例标签' },
            { index: 1, value: '第二对象' },
          ],
          success() {
            closeChannel({ success() { destroy({}) } })
          },
          fail(err) {
            console.error(err.errCode, err.errMsg)
          },
        })
      },
    })
  },
})

6. 权限

请在应用 manifest / 隐私弹窗中声明上述用途为连接并打印至附近的兄弟打印机。

7. 错误码（909）

8. 平台注意

• uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.1.6+ 并重打自定义基座
• Android 打印图像/PDF 前请确保 workPath 可写；默认使用应用外部文件目录
• iOS 经典蓝牙打印机通常需 MFi；address 使用 External Accessory 序列号，不是 BLE MAC
• iOS BLE 使用打印机广播 localName 作为 address
• printerModel / labelSize 必须与实机及装入标签一致，否则 SDK 返回打印错误
• RJ / TD / PJ 等机型可将 printerModel 透传 Android 枚举名，但不承诺全测
• 模板打印要求打印机内已安装对应 key 的 P-touch 模板；本插件不做模板文件大批量传输（详见 §4.3）
• wifi / ble 搜索建议已知 IP、MFi 序列号或 BLE localName 后直连
• onDisconnected：类型与 init 参数已提供，但当前 Android/iOS 实现未注册 Brother SDK 被动断线监听；断线请用 getConnectionState 或下次打印/状态 API 的 fail 感知，勿依赖该回调