Swift SDK

Swift SDK 适用于 iOS 和 macOS 现代应用开发，通过 BLE（低功耗蓝牙）连接打印机设备。

开发中

原生 Swift SDK 正在积极开发中，目前可通过 Objective-C Framework 桥接使用。

安装

1. 下载 Framework

从 GitHub 下载 Framework：Package Center

2. 导入 Framework

必须导入：

• adapter.framework - 设备适配器
• father.framework - 核心框架

按需导入：

• cpcl.framework - CPCL 指令
• esc.framework - ESC 指令
• tspl.framework - TSPL 指令

3. 创建桥接头文件

创建 YourProject-Bridging-Header.h：

#import <adapter/adapter.h>
#import <father/father.h>
#import <tspl/tspl.h>
#import <cpcl/cpcl.h>
#import <esc/esc.h>

在 Build Settings 中设置 Objective-C Bridging Header 路径。

快速开始

初始化打印机管理器

import Foundation
import CoreBluetooth

class PrinterManager: NSObject {
    private var lifecycle: Lifecycle?
    private var connectedPeripheral: CBPeripheral?

    func connect(device: CBPeripheral) {
        lifecycle = Lifecycle()
        lifecycle?.connectedDevice(device)
        connectedPeripheral = device
    }

    func disconnect() {
        connectedPeripheral = nil
        lifecycle = nil
    }
}

ESC 指令使用

ESC 指令广泛用于热敏小票打印机。详细指令说明请参考 ESC 指令文档。

初始化 ESC

private var escCommand: AYEscCommand?

func setupESC() {
    escCommand = AYEscCommand()
}

完整打印流程

func printReceipt() {
    guard let esc = escCommand else { return }

    // 1. 唤醒打印机
    esc.wake()

    // 2. 使能打印机
    esc.enable()

    // 3. 打印图片
    if let image = UIImage(named: "receipt") {
        esc.image(image, compress: false, mode: .normal)
    }

    // 4. 打印定位（连续纸不需要）
    esc.position()

    // 5. 结束打印任务
    esc.stopPrintJob()

    // 6. 发送指令
    bleHelper?.writeCommands(esc.commands)
}

打印指令

// 唤醒打印机
esc.wake()

// 使能打印机
esc.enable()

// 打印图片
esc.image(image, compress: false, mode: .normal)

// 打印定位
esc.position()

// 结束打印任务
esc.stopPrintJob()

设置指令

// 设置关机时间（单位：分钟，0 表示不关机）
esc.shutTime(10)

// 设置浓度
esc.thickness(.medium)  // .low, .medium, .high

// 设置纸张类型
esc.paperType(.continuous)  // .blackMark, .continuous, .gap, .hole

查询指令

// 查询打印机信息
esc.printerInfo()

// 查询打印机状态
esc.state()

// 查询电量
esc.batteryVol()

// 查询蓝牙名称
esc.btName()

// 查询固件版本
esc.printerVersion()

// 查询 MAC 地址
esc.mac()

// 查询 SN 号
esc.sn()

// 查询打印机型号
esc.printerModel()

// 发送指令
bleHelper?.writeCommands(esc.commands)

设置回调

// 设置回调处理打印机返回数据
escCommand?.read = { [weak self] data, error in
    if let data = data {
        print("打印机回传: \(data)")
        // 解析查询结果或状态信息
    }
}

TSPL 指令使用

TSPL 指令用于标签条码打印机。详细指令说明请参考 TSPL 指令文档。

初始化 TSPL

private var tspl: BasicTSPL?

func setupTSPL() {
    tspl = BasicTSPL()
    tspl?.basicTSPL(lifecycle, TSPLPrinter_GENERIC)

    // 设置回调
    tspl?.read = { [weak self] data, error in
        if let data = data {
            print("打印机回传: \(data)")
        }
    }

    tspl?.bleDidConnectPeripheral = { peripheral in
        print("连接成功: \(peripheral.name ?? "")")
    }

    tspl?.bleDidDisconnectPeripheral = { peripheral, error in
        print("连接断开: \(error?.localizedDescription ?? "")")
    }
}

打印标签

func printLabel() {
    guard let tspl = tspl else { return }

    // 页面设置
    let page = TPage().width(60).height(40)
    let direction = TDirection().direction(.up_out).mirror(.no_mirror)

    // 文字
    let title = TText()
        .x(180).y(30)
        .font(.TSS24)
        .xmulti(2).ymulti(2)
        .content("商品标签")

    // 条码
    let barcode = TBarcode()
        .x(100).y(200)
        .type("128")
        .height(60)
        .content("6901234567890")

    // 二维码
    let qrcode = TQRCode()
        .x(350).y(100)
        .cellWidth(4)
        .content("https://example.com")

    // 执行打印
    tspl.page(page)
        .direction(direction)
        .gap(true)
        .cls()
        .text(title)
        .barcode(barcode)
        .qrcode(qrcode)
        .print(1)
}

CPCL 指令使用

CPCL 指令用于便携式标签打印机。详细指令说明请参考 CPCL 指令文档。

初始化 CPCL

private var cpcl: BasicCPCL?

func setupCPCL() {
    cpcl = BasicCPCL()
    cpcl?.basicCPCL(lifecycle)
}

打印标签

func printCPCLLabel() {
    guard let cpcl = cpcl else { return }

    // 页面设置
    let page = CPCLPage().width(576).height(400)

    // 文字
    let title = CPCLText()
        .x(50).y(50)
        .content("商品标签")

    // 条码
    let barcode = CPCLBarcode()
        .x(50).y(150)
        .content("1234567890")

    // 执行打印
    cpcl.page(page)
        .text(title)
        .barcode(barcode)
        .print()
}

蓝牙连接管理

BLE 搜索设备

import CoreBluetooth

class BluetoothManager: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
    private var centralManager: CBCentralManager!
    private var discoveredPeripherals: [CBPeripheral] = []

    override init() {
        super.init()
        centralManager = CBCentralManager(delegate: self, queue: nil)
    }

    func startScan() {
        if centralManager.state == .poweredOn {
            centralManager.scanForPeripherals(withServices: nil, options: nil)
        }
    }

    func stopScan() {
        centralManager.stopScan()
    }

    func connect(_ peripheral: CBPeripheral) {
        centralManager.connect(peripheral, options: nil)
    }

    // MARK: - CBCentralManagerDelegate

    func centralManagerDidUpdateState(_ central: CBCentralManager) {
        if central.state == .poweredOn {
            print("蓝牙已开启")
        }
    }

    func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral,
                        advertisementData: [String: Any], rssi RSSI: NSNumber) {
        if !discoveredPeripherals.contains(peripheral) {
            discoveredPeripherals.append(peripheral)
            print("发现设备: \(peripheral.name ?? "Unknown")")
        }
    }

    func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
        print("连接成功: \(peripheral.name ?? "")")
        peripheral.delegate = self
        peripheral.discoverServices(nil)
    }

    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral,
                        error: Error?) {
        print("连接断开: \(error?.localizedDescription ?? "")")
    }
}

权限配置

在 Info.plist 中添加：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限来连接打印机</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要蓝牙权限来连接打印机</string>

路线图

• 原生 Swift Package
• 完整的 Swift API
• async/await 支持
• SwiftUI 集成示例
• Combine 支持
• macOS 支持优化

示例项目

完整示例请参考：

• iOS Demo (Swift)
• psdk-examples

参考文档

• ESC 完整指令文档 (PDF)
• iOS Bluetooth 开发文档

获取更新

关注我们的 GitHub 获取最新进展。

反馈

如果你对 Swift SDK 有任何建议或需求，欢迎提交 Issue。