更新记录

1.1.0（2025-09-01）

• iOS支持;
• TSPL指令支持;

1.0.0（2025-08-28）

• 安卓蓝牙、usb;
• CPCL指令支持;

平台兼容性

uni-app(4.76)

xl-XPrinter开发文档

UTS插件通用试用流程：

• 点击 使用 HBuilderX 导入示例项目 导入项目到 HBuilderX 中;
• 点击 试用 导入插件到 示例项目 中;
• 选择云端证书打包自定义基座;
• 使用自定义基座运行，即可体验示例项目;

📦 导入

import * as xPrinter from "@/uni_modules/xl-XPrinter"

🔍 蓝牙使用说明

蓝牙设备信息

export type XBlueDevice = {
    deviceId : string   // iOS: uuid, Android: mac 地址
    name : string       // 蓝牙设备名称
    paired ?: boolean   // 是否已配对（Android）
}

扫描设备

xPrinter.scanBlue((device) => {
    console.log(`find device ${JSON.stringify(device)}`);
})

停止扫描设备

xPrinter.stopScanBlue()

连接蓝牙设备

xPrinter.connectBlue(deviceId) // deviceId 为 device 对象中的 device.deviceId

断开蓝牙设备

xPrinter.disconnect()

🖥 USB 使用说明

USB设备信息

// USB设备信息
export type XUsbDevice = {
    deviceName : string     // 设备名称
    deviceId : string       // 设备 ID
    productName : string    // 产品名称
    productId : string      // PID
    vendorId : string       // VID
    manufacturerName : string   // 厂商名
}

获取 USB 设备列表

const devices = xPrinter.getUsbDevices()

连接USB

xPrinter.connectUsb(name) 

断开USB

xPrinter.disconnect() 

🌐 网络打印使用说明

网络打印参数

// net设备信息
{
  ip: string;   // 打印机IP地址
  port: string; // 打印端口
}

连接

xPrinter.connectNet({ ip: '192.168.0.100', port: '9100' });

断开

xPrinter.disconnect() 

回调

蓝牙状态改变回调

xPrinter.onBlueSateChange((isOn) => {
    console.log(`蓝牙 ${isOn ? '开启' : '关闭'}`);
});

连接状态改变回调

xPrinter.onConnectSateChange((payload) => {
    console.log('onConnectSateChange', payload);
    switch (payload.state) {
        case 'connectSuccess':
            uni.showToast({
                title: `connectSuccess: ${payload}`
            })
            break;
        case 'disconnect':
            uni.showToast({
                title: `disconnect: ${payload}`
            })
            break;
        case 'connectFail':
            break;
    }
})

payload说明

export type ConnectBack = {
    state : ConnectState    // 连接状态 'connectSuccess' | 'connectFail' | 'disconnect'
    type : ConnectType      // 连接类型 'blue' | 'usb' | 'net'
    info : string           // 为蓝牙 MAC 地址 或 USB 路 径 名 (“/dev/bus/usb/002/003”) 或 网络的 IP 地址
    mseeage : string        // 提示信息
};
export type ConnectType = 'blue' | 'usb' | 'net';
export type ConnectState = 'connectSuccess' | 'connectFail' | 'disconnect';

指令文档